Natural wildlife documentary, a single anatomically correct giant anteater beside a red-earth termite mound in open dry Brazilian cerrado, ochre grass and scattered low scrub under bright afternoon light. Low medium side view, locked camera, entire long snout and forequarters visible. It brings its nose close to a small hole, gives one brief sneeze that lifts a tiny puff of loose red dust, then blinks and holds still. Its long muzzle, small ears, bushy tail and coat markings remain consistent. Audio: one soft animal sneeze exactly on the head movement, dry wind and distant insects, no human voice or music. One continuous five-second shot. No cuts, subtitles, captions, visible writing, logos, advertising or watermarks.
Wan 2.5 Text to Video API
alibaba/wan-2.5/text-to-videoWan 2.5 Text to Video turns written scenes into videos with synchronized audio and output up to 1080p. It follows descriptions of subjects, actions, and camera movement to build coherent shots with sound that matches the scene.
902/1500
OutputVideo ready
Examples
Developer integration
Quick Start
Submit a request to the generation endpoint, then query the video using its task ID. Choose cURL, JavaScript, or Python for the example.
01
Set up authentication
Configure VIDGO_API_KEY on your server and pass it as a Bearer token in the Authorization header.
- Submission endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer VIDGO_API_KEY
02
Submit the generation request
Send model and input in a POST request to the generation endpoint. Save the returned task_id after a successful submission.
Submission example
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-2.5/text-to-video",
"input": {
"prompt": "At dawn, a red bicycle crosses a stone bridge beside a river. The camera tracks smoothly from the side as sunlight filters through leaves, with wheel sounds and birdsong.",
"aspect_ratio": "1280*720",
"duration": 5
}
}
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
Check execution status
Send a GET request using task_id until the status becomes finished or failed.
Task lookup
GET https://api.vidgo.ai/api/generate/status/{task_id}Replace {task_id} in the URL with the identifier from the submission response and query using the same Bearer token.
not_startedrunningfinishedfailedSubmission response
{
"code": 200,
"data": {
"task_id": "task-wan25-example",
"status": "not_started",
"created_time": "2026-09-27T00:00:00Z"
}
}Completion response
{
"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
}
}Read the video file
On completion, read the video URL from data.files. On failure, read data.error_message and review the request.
Read the video file
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-2.5/text-to-video",
"input": {
"prompt": "At dawn, a red bicycle crosses a stone bridge beside a river. The camera tracks smoothly from the side as sunlight filters through leaves, with wheel sounds and birdsong.",
"aspect_ratio": "1280*720",
"duration": 5
}
}
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
Place these parameters inside the request’s input object and set model to this page’s model identifier.
| Field | Type | Required | Default | Usage and values |
|---|---|---|---|---|
| prompt | string | Yes | — | Use 1–1500 characters to describe the subject, setting, action, and camera movement, followed by ambient sound or music. |
| aspect_ratio | string | Yes | — | Select width*height in pixels: 832*480, 480*832, 1280*720, 720*1280, 1920*1080, or 1080*1920. |
| duration | integer | No | 5 | Choose 5 or 10 seconds. The default is 5; the displayed cost updates with the duration. |
| audio | string | No | — | Optionally provide a publicly accessible audio file URL for speech or music. Leave it empty to generate sound that matches the video. |
| negative_prompt | string | No | — | Optionally describe unwanted visual elements, such as blur, lettering, or extra people. |
| seed | integer | No | — | Optionally enter an integer to record the random seed alongside your prompt and generation settings. |
Response Fields
The submission response identifies the task. Status responses provide its execution state and video files.
| Field | Type | Usage and values |
|---|---|---|
| code | integer | Application result code; 0 or 200 indicates a successful request. |
| data.task_id | string | Identifier of the generation task, used for subsequent status checks. |
| data.status | string | Task state: not_started, running, finished, or failed. |
| data.files | array<object> | Files returned on completion. Read file_url from entries whose file_type is video. |
| data.error_message | string | null | Error details for a failed task, used to review assets or adjust the request. |
Task Lifecycle
Save the task_id from submission and use that identifier to follow the task until it finishes or fails.
not_startedThe task has been created and is waiting to start.
runningThe task is processing; continue checking the same task.
finishedThe task is complete; read the video URL from files.
failedThe task failed; read error_message and review the input.
Status Checks and Error Handling
- Keep the same task IDAfter receiving task_id, use it to check progress. If a network error interrupts a status check, retry the check for that same task.
- Review the request by fieldFor validation errors, check required fields, types, and enumerated values. Image and audio URLs should be publicly accessible.
- Inspect the completion responseWhen the status is finished, read the video file entry. If file_url is missing, retain task_id and the response for troubleshooting.
Model Specifications
| Specification | Value | Details |
|---|---|---|
| Input mode | Text prompt | Describe the subject, setting, action, and sound in text. |
| Video duration | 5 / 10 seconds | Select the clip length with duration; the default is 5 seconds. |
| Output resolution | 480p / 720p / 1080p | Select clarity and orientation through the six width*height presets in aspect_ratio. |
| Audio mode | Generated / Custom audio | Generate matching sound with the video, or supply a publicly accessible audio file URL through audio. |
Related Models
Wan 2.5 Text to Video API frequently asked questions
What is the Wan 2.5 Text to Video API?
Wan 2.5 Text to Video is an Alibaba Tongyi model for generating videos from written descriptions. It creates 5 or 10-second clips with synchronized audio, coherent motion, and output up to 1080p. Native audiovisual generation brings the described subject, action, and sound into one scene while the prompt guides camera movement. You can call it programmatically or try it from the playground above.
Does Wan 2.5 Text to Video generate synchronized audio?
Yes. The model generates sound that matches the prompt and visuals. Describe audio alongside the scene’s action, such as turning wheels, rainfall, or soft music, so picture and sound develop around the same moment.
How can I use custom audio with Wan 2.5 Text to Video?
Enter a publicly accessible audio file URL in Audio to supply an existing voice track or music. Describe the corresponding subject, setting, and action in the prompt so the visuals can develop around the recording.
How do I guide camera movement in Wan 2.5 Text to Video?
Describe the camera’s direction and speed in the prompt, such as “slowly push in toward the face” or “track the bicycle smoothly from the side.” Separate subject action from camera action and use one main camera movement for the clip.
Can Wan 2.5 Text to Video generate a 10-second clip?
Yes. Set Duration to 10; the default is 5 seconds. Use 5 seconds for a brief action, or 10 seconds to give a slow camera move or a longer action more room.
How do I select 1080p in Wan 2.5 Text to Video?
Choose 1920*1080 for landscape or 1080*1920 for portrait in Aspect Ratio. This parameter takes width*height pixel dimensions; the other four presets cover 480p and 720p for choosing the orientation and clarity of your shot.
How should I structure a scene prompt for Wan 2.5 Text to Video?
Describe the subject, action, setting, lighting, camera, and sound in 1–1500 characters. Build around one main event and state the subject’s appearance or object details so the action and scene cues remain coherent.
How do I use negative prompts with Wan 2.5 Text to Video?
List unwanted elements in Negative Prompt, such as blur, lettering, or extra people, while describing the intended scene positively in Prompt. Record Seed and the other settings as you compare the effect of one change at a time.