Greenhouse Walk
Wan Animate Replace API
alibaba/wan/v2.2-14b/animate/replaceWan Animate Replace transforms the existing actor in a source video into a new subject from a reference image, delivering photorealistic character swapping, natural boundary blending, and multi-tier resolution options. It preserves original camera motion, scene lighting, and environmental interactions while accurately transferring the replacement character's facial likeness and attire.
Drag and drop files, paste from clipboard, or provide a URL. One image. Playground uploads: JPG, PNG or WebP, up to 10 MiB. The API requires an HTTP(S) URL array.
1/1 files added
Drag and drop files, paste from clipboard, or provide a URL. One video. Playground uploads: MP4, MOV or MKV, up to 100 MiB. Billing uses source duration rounded up to seconds.
1/1 files added
OutputReady
Examples
REST API Spec
Quick Start
Real generation example. The request below matches the default playground input; the response is from an actual test-environment submission.
01
Step 1: Configure API authentication
Obtain an API key from the dashboard and include Authorization: Bearer <API_KEY> in every request header.
- Submission Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Auth Header
- Authorization: Bearer VIDGO_API_KEY
02
Step 2: Submit a generation task
POST /api/generate/submit. Pass model and optional callback_url at the root level, with generation parameters inside input.
Request Payload
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan/v2.2-14b/animate/replace",
"input": {
"image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan/v2.2-14b/animate/replace/v1/01/input-image.png"
],
"video_url": "https://cdn.vidgo.ai/apis/models/alibaba/wan/v2.2-14b/animate/replace/v1/01/input-video.mp4",
"resolution": "480p"
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"03
Step 3: Poll for task completion
Poll status with task_id; continue while not_started or running, and stop on finished or failed. Read video URLs from data.files[].file_url on success, or data.error_message on failure.
Status Endpoint
GET https://api.vidgo.ai/api/generate/status/{task_id}Poll status using task_id; continue while not_started or running, stop when finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.
not_startedrunningfinishedfailedSubmission Response
{
"code": 200,
"data": {
"task_id": "ZO7YZOYR1AQH08U4",
"status": "running",
"created_time": "2026-09-23T09:56:34"
}
}Completed Response Data
{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}Complete end-to-end script example
Expand to view a production-ready script with retry logic, error handling, and timeout safeguards.
Complete end-to-end script example
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan/v2.2-14b/animate/replace",
"input": {
"image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan/v2.2-14b/animate/replace/v1/01/input-image.png"
],
"video_url": "https://cdn.vidgo.ai/apis/models/alibaba/wan/v2.2-14b/animate/replace/v1/01/input-video.mp4",
"resolution": "480p"
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneRequest Parameters (input object)
POST /api/generate/submit accepts only the following input fields. Set model and optional callback_url at the root. URLs must contain a hostname and no credentials or whitespace.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| image_urls | array<string> | Yes | — | Exactly one public HTTP(S) image URL in an array. Bare strings and Base64 are rejected. |
| video_url | string | Yes | — | Required public HTTP(S) source video URL. Vidgo inspects files up to 100 MiB. Duration must be positive; do not send a duration field. |
| resolution | string | No | 480p | 480p, 580p or 720p. Defaults to 480p only when omitted. Null, empty strings, aliases and surrounding whitespace are rejected. |
Response Fields (query result)
Task details returned when polling GET /api/generate/status/{task_id}:
| Field | Type | Description |
|---|---|---|
| code | integer | Business response code, 200 on success. |
| data.task_id | string | Globally unique asynchronous task identifier. |
| data.status | string | Execution status: not_started, running, finished, or failed. |
| data.files | array | Generated video files upon completion, each with file_url and file_type. |
| data.error_message | string | null | Error description if task fails. |
Task Lifecycle
Clients should inspect the status field and stop polling when reaching finished or failed:
not_startedTask received and queued for execution.
runningGeneration is in progress.
finishedGeneration complete; retrieve video URL from data.files.
failedGeneration failed; inspect data.error_message; deducted credits are refunded per standard policy.
Polling & Error Handling
- Recommended Polling IntervalThe playground increases the polling interval from 2 seconds up to 10 seconds and stops on finished or failed.
- Network Fluctuations & RetriesA failed status query does not mean generation failed. Retry the status query for the same task without resubmitting.
- Asynchronous Webhook CallbackProvide callback_url at the root of the request payload to receive the completed task result automatically via POST.
Specifications
| Specification | Value | Description |
|---|---|---|
| Model ID | alibaba/wan/v2.2-14b/animate/replace | Use this value in the root model field. |
| Resolution | 480p / 580p / 720p | 480p, 580p or 720p. Defaults to 480p only when omitted. Null, empty strings, aliases and surrounding whitespace are rejected. |
| Billing | 7 / 12 / 15 credits/sec | Estimated credits = ceil(source video seconds) × the resolution rate. Vidgo measures duration on the server. For example, 5.1 seconds at 480p costs 42 credits ($0.210). Media inspection errors are rejected before deduction; failed tasks are refunded. |
Related Models
Wan Animate Replace API Frequently Asked Questions
What is the Wan Animate Replace API?
Wan Animate Replace is an Alibaba model for video character replacement from reference images. It swaps the existing actor in a source video with a target character portrait while preserving camera motion, lighting interactions, and scene geometry across 480p, 580p, and 720p resolutions. Built on Wan2.2-Animate's 14B parameter multimodal architecture, it maintains original background composition while seamlessly mapping the new character's identity and clothing into the performance. You can call it programmatically or try it from the playground above.
How does Wan Animate Replace preserve the original background and camera motion?
Wan Animate Replace utilizes spatio-temporal diffusion attention that decouples actor segmentation masks from static and dynamic background elements. It tracks the original camera trajectory, zooming, and focal depth across all frames, ensuring only the target character region is transformed while the surrounding environment remains pixel-stable.
What inputs are required for Wan Animate Replace?
Wan Animate Replace requires two primary inputs: one source video URL (via video_url) containing the character to be replaced, and an image_urls array containing exactly one public HTTP(S) URL of the replacement subject portrait. Output resolution can optionally be set to 480p, 580p, or 720p.
How does Wan Animate Replace blend the new character into complex lighting?
The model incorporates ambient light adaptation that estimates direction, specular highlights, and color temperature from the driving footage. It realistically casts dynamic shadows from the new character onto nearby objects and reflects environmental hues onto the replacement character's skin and clothing.
How does Wan Animate Replace calculate credits?
Credits are calculated by measuring the source video duration on the server, rounding up to the nearest whole second, and multiplying by the chosen resolution rate: 7 credits/sec ($0.035/sec) for 480p, 12 credits/sec ($0.060/sec) for 580p, and 15 credits/sec ($0.075/sec) for 720p. Deducted credits are automatically refunded if generation fails.
What resolutions does Wan Animate Replace support?
Wan Animate Replace supports 480p (default), 580p, and 720p output resolutions. Use 480p for fast composition testing, 580p for social media formats, and 720p for final broadcast-ready high-definition deliverables.
When is Wan Animate Replace preferable to Wan Animate Move?
Wan Animate Replace is preferable when you already have a complete, polished scene and need to substitute an actor while preserving the complex environment, props, camera movements, and lighting. Wan Animate Move is designed to animate a standalone character portrait using extracted motion without retaining the reference video's background.