The resources (image, video) generated by our API are valid for 7 days.
Please save the relevant resources as soon as possible to prevent expiration.
Endpoint POST https://openapi.akool.com/api/open/v4/characterSwap/create
Parameter Value Description x-api-key API Key Your API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded. Authorization Bearer {token} Your API Key used for request authorization.Get Token
Body Attributes Parameter Type Required Description image String true Character image URL (PNG or JPEG) to be animated video String true Source video URL (MP4) with motion to apply duration Number false Video duration in seconds (1-120). If not provided, will be automatically detected from the video resolution String false Output resolution: 480p, 720p, 1080p (default: 720p) mode String false Animation mode: “animate” (character animation) or “replace” (face replacement) (default: “animate”) prompt String false Optional prompt text for generation guidance (max 500 characters) webhookurl String false Callback URL for POST requests
Response Attributes Parameter Type Description code Integer Interface returns business status code (1000:success) msg String Interface returns status information data Object Response data object - _id String Document ID - create_time Long Creation timestamp - uid Integer User ID - team_id String Team ID - status Integer Task status: 1=queueing, 2=processing, 3=completed, 4=failed - video_duration Number Video duration in seconds - deduction_credit Integer Credits deducted - resolution String Video resolution - file_name String Output file name - image_url String Input image URL - video_url String Input video URL - prompt String Animation prompt - mode String Animation mode - model_name String Model name used - webhookUrl String Callback URL
Example Request Body { "image" : "https://drz0f01yeq1cx.cloudfront.net/character-image.png" , "video" : "https://drz0f01yeq1cx.cloudfront.net/source-video.mp4" , "duration" : 10 , "resolution" : "720p" , "mode" : "animate" , "prompt" : "Smooth character animation with natural movement" , "webhookurl" : "https://your-callback-url.com/webhook" }
Request cURL
Java
Javascript
PHP
Python
curl --location 'https://openapi.akool.com/api/open/v4/characterSwap/create' \ --header 'x-api-key: {{API Key}}' \ --header 'Content-Type: application/json' \ --data '{ "image": "https://drz0f01yeq1cx.cloudfront.net/character-image.png", "video": "https://drz0f01yeq1cx.cloudfront.net/source-video.mp4", "duration": 10, "resolution": "720p", "mode": "animate", "prompt": "Smooth character animation with natural movement", "webhookurl": "https://your-callback-url.com/webhook" }'
Response { "code" : 1000 , "msg" : "OK" , "data" : { "_id" : "689174694b4dbdd4ab3d28c9" , "create_time" : 1754362985482 , "uid" : 101400 , "team_id" : "6805fb69e92d9edc7ca0b409" , "status" : 1 , "video_duration" : 10 , "deduction_credit" : 20 , "resolution" : "720p" , "file_name" : "CharacterSwap_1754362985482.mp4" , "image_url" : "https://drz0f01yeq1cx.cloudfront.net/character-image.png" , "video_url" : "https://drz0f01yeq1cx.cloudfront.net/source-video.mp4" , "prompt" : "Smooth character animation with natural movement" , "mode" : "animate" , "model_name" : "wavespeed-ai/wan-2.2/animate" , "webhookUrl" : "https://your-callback-url.com/webhook" } }
Important Notes
Image Quality : Use high-resolution images with clearly visible faces for better resultsVideo Format : MP4 format is required for source videosDuration : If not specified, duration will be automatically detected from the source video. Maximum is 120 secondsMode Options :
animate: Applies character animation to the image using the video’s motionreplace: Replaces faces in the video with the character from the image
Prompt : Use the prompt parameter for enhanced control over the animation (max 500 characters)Resolution : Choose between 480p or 720p or 1080p based on your needs - higher resolution may take longer to processResource Expiration : Generated videos are valid for 7 days, save them promptlyWebhook : Use webhookUrl to receive notifications when video generation is completeSave the _id from the response to check video status using the Get Video Info Result API
