> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Character Swap

> Create animated video from character image and source video using WaveSpeed AI's advanced animation models

<Warning>
  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.
</Warning>

## 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](/authentication/usage#get-the-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

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```java Java theme={null}
  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();
  ```

  ```js Javascript theme={null}
  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 PHP theme={null}
  <?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();
  ?>
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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](/ai-tools-suite/character-swap/get-result) API