> ## 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.5 Video
> Alibaba-style video generation API for text-to-video and image-to-video workflows
## Overview
Wan 2.5 generates short videos from a text prompt or from one reference image plus a prompt.
| Capability | Value |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Model ID | `wan-2-5-video` |
| Modes | `text-to-video`, `image-to-video` |
| Prompt | Max `1500` characters (`text-to-video` required and non-empty, `image-to-video` optional) |
| Negative prompt | Optional, max `500` characters |
| Reference images | `image-to-video` requires exactly 1 URL; `JPEG/JPG/PNG(no alpha)/BMP/WEBP`, width and height `240-8000` px, file size `<=20MB` |
| Audio input | `audio_urls` optional with exactly 1 URL; `wav/mp3`, `3-30s`, file size `<=15MB` |
| Resolutions | `480p`, `720p`, `1080p` |
| Duration | `5` or `10` seconds |
| Prompt rewrite | `prompt_extend` optional boolean; `true` (default) enables rewrite, `false` disables rewrite |
| Text-to-video aspect ratios | `16:9`, `9:16`, `1:1` (all resolutions), plus `4:3`, `3:4` for `720p`/`1080p` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/wan-2-5-video` | Submit a generation task |
| `GET` | `/statusTask/wan-2-5-video?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
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/wan-2-5-video" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a cinematic shot of clouds drifting over a quiet mountain lake",
"audio_urls": [
"https://example.com/music.mp3"
],
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9",
"prompt_extend": true
}
}'
```
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-5-video?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": 1767965752317,
"costTime": 141388
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "INVALID_PARAMETER",
"failMsg": "The parameter {{resolution}} is invalid",
"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
### Text-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a serene mountain landscape with moving clouds and gentle breeze",
"audio_urls": [
"https://example.com/music.mp3"
],
"resolution": "480p",
"duration": 5,
"aspect_ratio": "1:1",
"prompt_extend": true,
"negative_prompt": "low quality, blurry",
"watermark": false,
"seed": 20260413
}
}
```
### Image-to-video
```json theme={null}
{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "image-to-video",
"image_urls": [
"https://example.com/reference.png"
],
"prompt": "turn this photo into a smooth cinematic shot with a slow push-in camera move",
"audio_urls": [
"https://example.com/music.mp3"
],
"resolution": "1080p",
"duration": 10
}
}
```
## 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.5 input parameters.
Generation mode. Supported values: `text-to-video`, `image-to-video`.
Prompt text. Required for `text-to-video`; optional for `image-to-video`. Supports Chinese and English; maximum length is `1500` characters.
Reference image URL list. Required for `image-to-video`. Must contain exactly 1 URL. Image constraints: formats `JPEG/JPG/PNG` (no alpha), `BMP`, `WEBP`; width and height `240-8000` px; file size `<= 20MB`.
Optional audio URL list. Supports exactly 1 URL. Audio constraints: formats `wav/mp3`, duration `3-30s`, file size `<= 15MB`. If audio is longer than `duration`, only the first `duration` seconds are used; if audio is shorter than output video duration, the remaining segment is silent.
Output resolution. Supported values: `480p`, `720p`, `1080p`.
Output duration in seconds. Supported values: `5`, `10`.
Whether to enable prompt rewriting before generation. `true` (default) enables rewriting and can improve short prompts but may increase latency. `false` disables rewriting.
Text-to-video only. `480p` supports `16:9`, `9:16`, `1:1`; `720p` and `1080p` support `16:9`, `9:16`, `1:1`, `4:3`, `3:4`.
Optional negative prompt describing what to avoid. Supports Chinese and English; maximum length is `500` characters.
Optional watermark switch. `false` (default) means no watermark. `true` adds a bottom-right watermark with fixed text `AI 生成`.
Optional random seed in `[0, 2147483647]`. A fixed seed improves reproducibility, but identical seeds do not guarantee identical outputs.
## Response format
### Submit task response
`POST /generateTask/wan-2-5-video` 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.
## 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-5-video" \
-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": "text-to-video",
"prompt": "a polished product demo video with gentle camera movement",
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9"
}
}'
```
See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Wan 2.5 is billed per generated second.
| Mode | Resolution | Unit price |
| ---------------- | ---------- | ---------------- |
| `text-to-video` | `480p` | `$0.05 / second` |
| `text-to-video` | `720p` | `$0.10 / second` |
| `text-to-video` | `1080p` | `$0.15 / second` |
| `image-to-video` | `480p` | `$0.05 / second` |
| `image-to-video` | `720p` | `$0.10 / second` |
| `image-to-video` | `1080p` | `$0.15 / second` |
Final cost formula:
```text theme={null}
total_cost = duration_seconds * resolution_unit_price
```
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Video generation is long-running. Actual latency may vary by prompt complexity, mode, selected resolution, and current queue load.
| Request shape | Typical generation time | Recommended first poll | Poll interval |
| ------------- | ----------------------- | ----------------------- | ------------- |
| `480p` | 40s-120s | 40s after task creation | 10s |
| `720p` | 60s-180s | 60s after task creation | 10s |
| `1080p` | 90s-250s | 90s after task creation | 10s |
For high-concurrency production workloads, use callback mode to avoid frequent polling.
Practical notes:
* Use `aspect_ratio` only with `text-to-video`.
* `audio_urls` supports one MP3/WAV URL with max 15 MB; recommended duration range is 3-30 seconds.
* For `image-to-video`, `image_urls` must contain exactly one image URL and the image file should be at most 20 MB.
* Result URLs are temporary. Download important outputs promptly.
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, or media URL shape | 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 account cannot access the model | Check account permissions |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error | Retry with backoff |
| `502` | Third-party model service error | Retry with backoff |
| `504` | Third-party model timeout | Retry or use callback mode for long-running jobs |
### Task failure codes
| Fail code | Meaning | What to do |
| ---------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `CONTENT_VIOLATION` | Prompt or reference image failed safety checks | Change the prompt or input image |
| `INVALID_IMAGE_URL` | A reference image URL could not be fetched or decoded | Use a public, direct media URL |
| `INVALID_PARAMETER` | A model parameter is unsupported or malformed | Check `mode`, `resolution`, `duration`, `aspect_ratio`, `image_urls`, and `audio_urls` |
| `INSUFFICIENT_BALANCE` | The account does not have enough balance for the task | Add balance before retrying |
| `TIMEOUT` | Generation did not finish in time | Retry, reduce input complexity, or use callback mode |
### Parameter troubleshooting
* `prompt` is required for `text-to-video`, optional for `image-to-video`.
* `image_urls` is required only for `image-to-video` and must contain exactly one URL.
* `audio_urls` supports exactly one MP3/WAV URL when provided; file size should be ≤ 15 MB and recommended duration range is 3-30 seconds.
* `resolution` defaults to `1080p` when omitted.
* `duration` defaults to `5` when omitted and only accepts `5` or `10`.
* `aspect_ratio` applies only to `text-to-video`.
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)
* [Pricing](https://apixo.ai/pricing)