Create Character Swap

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

Request Headers

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 --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"
}'

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"image\": \"https://drz0f01yeq1cx.cloudfront.net/character-image.png\",\n  \"video\": \"https://drz0f01yeq1cx.cloudfront.net/source-video.mp4\",\n  \"duration\": 10,\n  \"resolution\": \"720p\",\n  \"mode\": \"animate\",\n  \"prompt\": \"Smooth character animation with natural movement\",\n  \"webhookurl\": \"https://your-callback-url.com/webhook\"\n}");
Request request = new Request.Builder()
  .url("https://openapi.akool.com/api/open/v4/characterSwap/create")
  .method("POST", body)
  .addHeader("x-api-key", "{{API Key}}")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

const myHeaders = new Headers();
myHeaders.append("x-api-key", "{{API Key}}");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "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"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://openapi.akool.com/api/open/v4/characterSwap/create", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

<?php
$client = new Client();
$headers = [
  'x-api-key' =>'{{API Key}}',
  'Content-Type' => 'application/json'
];
$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 = new Request('POST', 'https://openapi.akool.com/api/open/v4/characterSwap/create', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>

import requests
import json

url = "https://openapi.akool.com/api/open/v4/characterSwap/create"

payload = json.dumps({
  "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"
})
headers = {
  'x-api-key':'{{API Key}}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

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 results
Video Format: MP4 format is required for source videos
Duration: If not specified, duration will be automatically detected from the source video. Maximum is 120 seconds
Mode Options:
- animate: Applies character animation to the image using the video’s motion
- replace: 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 process
Resource Expiration: Generated videos are valid for 7 days, save them promptly
Webhook: Use webhookUrl to receive notifications when video generation is complete
Save the _id from the response to check video status using the Get Video Info Result API

Authentication

Face Swap

Streaming Avatar

Talking Photo

Video Translation

Face Detection

Character Swap

Image Generate

Image to Video

Head Swap

AI Tools Suite

Endpoint

Request Headers

Body Attributes

Response Attributes

Example

Request Body

Request

Response

Important Notes

​Endpoint

​Request Headers

​Body Attributes

​Response Attributes

​Example

​Request Body

​Request

​Response

​Important Notes

Endpoint

Request Headers

Body Attributes

Response Attributes

Example

Request Body

Request

Response

Important Notes