> ## Documentation Index > Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Wan 2.2 Animate > Alibaba character animation API combining one source image and one motion video ## Overview Wan 2.2 Animate is an Alibaba video model for character animation and character replacement. Use this page when you are ready to call the API after trying the model in the APIXO playground. | Capability | Value | | ---------------- | --------------------------------------------------------------------------------- | | Model ID | `wan-2-2-animate` | | Mode | `standard` | | Behaviors | `animate`, `replace` | | Source image | Exactly 1 URL in `image_urls` | | Motion video | Exactly 1 public HTTP/HTTPS MP4, MOV, or M4V URL in `video_urls` | | Resolution | `480p`, `720p` | | Billing duration | Detected from `video_urls[0]`, minimum 5 seconds and maximum 120 billable seconds | | Seed | `-1` or `0` to `2147483647` | ## Endpoint and authentication Base URL: ```text theme={null} https://api.apixo.ai/api/v1 ``` | Method | Endpoint | Purpose | | ------ | --------------------------------------------- | ------------------------------------- | | `POST` | `/generateTask/wan-2-2-animate` | Submit a generation task | | `GET` | `/statusTask/wan-2-2-animate?taskId={taskId}` | Poll task status and retrieve results | All requests require your APIXO API key: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` Submit requests also require: ```http theme={null} Content-Type: application/json ``` ## Copy-paste async quickstart This minimal request submits an animate task and returns a `taskId`. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/wan-2-2-animate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "async", "input": { "mode": "standard", "type": "animate", "image_urls": [ "https://example.com/character.png" ], "video_urls": [ "https://example.com/motion.mp4" ], "resolution": "480p", "seed": -1 } }' ``` Successful response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678" } } ``` Save the `taskId`; you need it to poll for the final result. ## Poll for result ```bash theme={null} curl -X GET "https://api.apixo.ai/api/v1/statusTask/wan-2-2-animate?taskId=task_12345678" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Processing response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "processing", "createTime": 1767965610929 } } ``` Success response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "success", "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}", "createTime": 1767965610929, "completeTime": 1767965772317, "costTime": 161388 } } ``` Failed response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "failed", "failCode": "PromptInvalid", "failMsg": "Prompt is invalid or rejected", "createTime": 1767965610929, "completeTime": 1767965620132 } } ``` Parse `resultJson` after `state` becomes `success`: ```javascript theme={null} const payload = JSON.parse(data.resultJson); const videoUrls = payload.resultUrls; ``` ## Request body ### Animate Use `type: "animate"` to animate the character in the source image with motion from the reference video. ```json theme={null} { "request_type": "async", "input": { "mode": "standard", "type": "animate", "image_urls": [ "https://example.com/character.png" ], "video_urls": [ "https://example.com/motion.mp4" ], "prompt": "keep the face stable and follow the motion naturally", "resolution": "480p", "seed": -1 } } ``` ### Replace Use `type: "replace"` to replace the character in the motion video with the character from the source image. ```json theme={null} { "request_type": "async", "input": { "mode": "standard", "type": "replace", "image_urls": [ "https://example.com/character.png" ], "video_urls": [ "https://example.com/motion.mp4" ], "prompt": "replace the person in the motion video with the provided character", "resolution": "720p", "seed": 42 } } ``` ## Parameters Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery. Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks). Wan 2.2 Animate input parameters. Public generation mode. Supported value: `standard`. Animation behavior. Supported values: `animate`, `replace`. Source image URLs. Provide exactly 1 URL. Motion reference video URLs. Provide exactly 1 public HTTP/HTTPS MP4, MOV, or M4V URL. APIXO probes `video_urls[0]` to detect billing duration before submitting the task. Optional prompt guidance. If provided, it must be a non-empty string. Output resolution. Supported values: `480p`, `720p`. Random seed. Use `-1` for a random seed, or set an integer from `0` to `2147483647` for reproducible runs. ## Response format ### Submit task response `POST /generateTask/wan-2-2-animate` returns a task ID when the task is accepted: API status code. `200` means the task was accepted. Human-readable status message. Unique task identifier used with the status endpoint. ### Status response fields Unique task identifier. Current task state: `pending`, `processing`, `success`, or `failed`. JSON string containing the generated video URLs. Present when `state` is `success`. Machine-readable failure code. Present when `state` is `failed`. Human-readable failure message. Present when `state` is `failed`. Task creation timestamp in Unix milliseconds. Task completion timestamp in Unix milliseconds. Present after completion. Processing duration in milliseconds. Present after successful completion when timing data is available. ## Webhook callback mode Use callback mode when your backend should receive the final result automatically instead of polling. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/wan-2-2-animate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "callback", "callback_url": "https://your-server.com/webhooks/apixo", "input": { "mode": "standard", "type": "replace", "image_urls": [ "https://example.com/character.png" ], "video_urls": [ "https://example.com/motion.mp4" ], "prompt": "replace the person in the motion video with the provided character", "resolution": "720p", "seed": 42 } }' ``` See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior. ## Billing Wan 2.2 Animate is billed per generated video second. The selected `resolution` determines the unit price, and billable duration is detected from `video_urls[0]`. | Resolution | Billing input | APIXO price | | ---------- | ------------------------------------------------------------------------------------- | ---------------- | | `480p` | Detected reference video duration, minimum 5 seconds and maximum 120 billable seconds | `$0.04 / second` | | `720p` | Detected reference video duration, minimum 5 seconds and maximum 120 billable seconds | `$0.08 / second` | If the reference video is shorter than 5 seconds, billing uses 5 seconds. If it is longer than 120 seconds, billing is capped at 120 seconds. For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing). ## Latency and polling Actual latency may vary by reference video duration, resolution, queue load, and current route health. | Request shape | Typical generation time | Recommended first poll | Poll interval | | ---------------------- | --------------------------------------------------- | ---------------------------- | ------------- | | Short `480p` animation | Varies with reference video duration and queue load | 60s after task creation | 5s-10s | | Short `720p` animation | Varies with reference video duration and queue load | 60s after task creation | 5s-10s | | Longer reference video | Varies with reference video duration and queue load | 60s-120s after task creation | 10s | Video generation can take several minutes. For production workloads, use callback mode to avoid frequent polling. Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system). ## Errors and troubleshooting ### HTTP errors | Code | Meaning | What to do | | ----- | -------------------------------------------------------------- | ------------------------------------------------ | | `400` | Invalid request body, mode, parameter, image URL, or video URL | Fix the request before retrying | | `401` | Missing or invalid API key | Check the `Authorization` header | | `402` | Insufficient balance or quota | Add balance or switch account/key | | `403` | Key or route cannot access the model, or content was rejected | Check permissions and revise input content | | `429` | Rate limit or concurrency limit reached | Retry with exponential backoff | | `500` | Server error | Retry with backoff | | `502` | Upstream service error | Retry with backoff | | `504` | Upstream timeout | Retry or use callback mode for long-running jobs | ### Task failure causes | Cause | What to check | | ------------------------------ | ---------------------------------------------------------------------------------------------- | | Content policy rejection | Revise the prompt, source image, or motion video | | Invalid mode or type | Use `mode: "standard"` and `type: "animate"` or `"replace"` | | Invalid media shape | Provide exactly 1 `image_urls` item and exactly 1 `video_urls` item | | Video URL cannot be probed | Use a direct public HTTP/HTTPS MP4, MOV, or M4V URL that supports range reads or full download | | Invalid resolution | Use `480p` or `720p` | | Invalid seed | Use `-1` or an integer from `0` to `2147483647` | | Upstream rate limit or timeout | Retry with backoff or switch to callback mode | ### Common fixes | Symptom | Fix | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | Request fails with invalid mode | Set `input.mode` to `standard` | | Request fails before task creation | Check that `video_urls[0]` is publicly reachable and has a supported MP4, MOV, or M4V media type | | Billing is higher than expected for a very short video | Videos shorter than 5 seconds are billed as 5 seconds | | Billing stops increasing for a long reference video | Billable duration is capped at 120 seconds | | No update for several minutes | Continue polling with backoff, or use callback mode for production | See [Error Codes](/api-reference/errors) for the full error reference. ## Related links * [Generation API Overview](/models) * [Generate Task](/api-reference/generate-task) * [Status Task](/api-reference/status-task) * [Webhooks](/api-reference/webhooks) * [Error Codes](/api-reference/errors) * [Parameter Specification](/api-reference/parameters) * [Routing Strategies](/concepts/routing-strategies) * [Pricing](https://apixo.ai/pricing)