> ## 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.

# Character Swap API Overview

> Comprehensive guide to the Character Swap API

<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>

## API Endpoints

### Character Swap Operations

* [Create Character Swap](/ai-tools-suite/character-swap/create) - Create animated video from character image and source video
* [Get Video Info Result](/ai-tools-suite/character-swap/get-result) - Retrieve character swap video results by ID

## Getting Started

### Basic Workflow

1. **Create Character Swap Video**:
   * Prepare your character image URL (PNG or JPEG)
   * Prepare your source video URL (MP4) with the motion to apply
   * Optionally provide duration, resolution, mode, and prompt
   * Call the [Create Character Swap API](/ai-tools-suite/character-swap/create) with your resources

2. **Check Results**:
   * Use the [Get Video Info Result API](/ai-tools-suite/character-swap/get-result) to check the status of your video
   * Download the result URL when the status is "Success" (video\_status = 3)

### Response Code Description

<Note>
  Please note that if the value of the response code is not equal to 1000, the request
  has failed or encountered an error.
</Note>

| Code | Description                                            |
| ---- | ------------------------------------------------------ |
| 1000 | Success                                                |
| 1003 | Parameter error or Parameter cannot be empty           |
| 1008 | The content you get does not exist                     |
| 1009 | You do not have permission to operate                  |
| 1015 | Create video error, please try again later             |
| 1101 | Invalid authorization or The request token has expired |
| 1102 | Authorization cannot be empty                          |
| 1200 | The account has been banned                            |

## Pricing

### Character Swap

| Resolution | Unit Credit (per 5 seconds) |
| ---------- | --------------------------- |
| 480p       | 5 credits                   |
| 720p       | 10 credits                  |
| 1080p      | 15 credits                  |

**Note:** Credits are calculated based on video duration in 5-second increments. For example, a 12-second video at 720p resolution would cost 30 credits (12 seconds ÷ 5 seconds × 10 credits).

## Video Status Codes

When checking results, the `video_status` field indicates the current state:

| Status | Description                                                         |
| ------ | ------------------------------------------------------------------- |
| 1      | In Queue - Your request is waiting to be processed                  |
| 2      | Processing - Character swap video is currently being generated      |
| 3      | Success - Video completed, result URL is available                  |
| 4      | Failed - Video generation failed, please check your input resources |

## Best Practices

### Image Requirements

* **Quality**: Use high-resolution images for better results
* **Face Visibility**: Ensure the character face is clearly visible and not obscured
* **Lighting**: Well-lit images produce better character swap results
* **Angle**: Frontal or slight angle faces work best

### Video Requirements

* **Format**: MP4 format is required
* **Quality**: Use clear, high-quality source videos
* **Duration**: Maximum video duration is 120 seconds
* **Motion**: The source video should contain the motion you want to apply to the character

### API Usage Tips

* **Webhook**: Use the `webhookUrl` parameter to receive notifications when processing is complete
* **Prompt**: Use the `prompt` parameter for generation guidance (max 500 characters)
* **Resolution**: Choose appropriate resolution (480p or 720p) based on your needs - higher resolution may take longer to process
* **Mode**: Choose between "animate" (character animation) or "replace" (face replacement) based on your use case
* **Result Cleanup**: Save generated videos promptly as they expire after 7 days

## Common Use Cases

### Basic Character Animation

Create a character animation video by applying motion from a source video:

```json theme={null}
{
  "image": "https://example.com/character-image.png",
  "video": "https://example.com/source-video.mp4",
  "duration": 10,
  "resolution": "720p",
  "mode": "animate",
  "model_name": "wavespeed-ai/wan-2.2/animate",
  "webhookurl": "https://your-callback-url.com/webhook"
}
```

### Character Animation with Prompt

Use the `prompt` parameter for enhanced control over the animation:

```json theme={null}
{
  "image": "https://example.com/character-image.png",
  "video": "https://example.com/source-video.mp4",
  "duration": 15,
  "resolution": "720p",
  "mode": "animate",
  "prompt": "Smooth character animation with natural movement and expressive gestures",
  "model_name": "wavespeed-ai/wan-2.2/animate",
  "webhookurl": ""
}
```

### Face Replacement Mode

Replace faces in a video with a character face:

```json theme={null}
{
  "image": "https://example.com/character-face.png",
  "video": "https://example.com/target-video.mp4",
  "resolution": "720p",
  "mode": "replace",
  "model_name": "wavespeed-ai/wan-2.2/animate",
  "webhookurl": ""
}
```

## Notes

* **Pro Plan Required**: Character Swap feature requires Pro plan or higher subscription
* **Video Duration**: If not specified, the duration will be automatically detected from the source video. Maximum duration 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
* **Webhook Callbacks**: If a webhook URL is provided, you will receive a POST request when the task status changes to completed (3) or failed (4)

## Support

For additional help and examples, check out our:

* [Authentication Guide](/authentication/usage)
* [Webhook Documentation](/ai-tools-suite/webhook)