Skip to main content
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.

​
API Endpoints

​
Character Swap Operations

​
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 with your resources
  2. Check Results:
    • Use the Get Video Info Result API to check the status of your video
    • Download the result URL when the status is “Success” (video_status = 3)

​
Response Code Description

Please note that if the value of the response code is not equal to 1000, the request has failed or encountered an error.
CodeDescription
1000Success
1003Parameter error or Parameter cannot be empty
1008The content you get does not exist
1009You do not have permission to operate
1015Create video error, please try again later
1101Invalid authorization or The request token has expired
1102Authorization cannot be empty
1200The account has been banned

​
Pricing

​
Character Swap

ResolutionUnit Credit (per 5 seconds)
480p5 credits
720p10 credits
1080p15 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:
StatusDescription
1In Queue - Your request is waiting to be processed
2Processing - Character swap video is currently being generated
3Success - Video completed, result URL is available
4Failed - 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: 
{
  "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: 
{
  "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: 
{
  "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: