Character Swap API Overview

​

API Endpoints

​

Character Swap Operations

• Create Character Swap - Create animated video from character image and source video
• Get Video Info 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 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

​

Pricing

​

Character Swap

​

Video Status Codes

​

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

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

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

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

• Authentication Guide
• Webhook Documentation