> ## 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 3.0 Video API
> Wan 3.0 video generation API with text-to-video, image-to-video, and multimodal reference-to-video workflows
## Overview
Wan 3.0 Video generates videos from prompts, first-frame or first-and-last-frame images, and multimodal reference inputs such as images, videos, audio files, files, and web links. Use this page when you are ready to call the API after trying the model in the APIXO playground.
| Capability | Value |
| --------------------- | -------------------------------------------------------------------------------------- |
| Model ID | `wan-3-0-video` |
| Modes | `text-to-video`, `image-to-video`, `reference-to-video` |
| Prompt | Required for `text-to-video`; optional for `image-to-video` and `reference-to-video` |
| Resolutions | `480p`, `720p`, `1080p` |
| Aspect ratios | `auto`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
| Duration | `-1` for smart duration, or any integer from `2` through `30` seconds; defaults to `5` |
| Image-to-video images | 1-2 image URLs; the second image is the optional last frame |
| Reference inputs | Up to 10 image URLs, 5 video URLs, 5 audio URLs, 1 file URL, or 1 link URL |
| Result format | MP4 URL array in `resultJson.resultUrls` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/wan-3-0-video` | Submit a generation task |
| `GET` | `/statusTask/wan-3-0-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
This minimal request submits a text-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/wan-3-0-video" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a cinematic product reveal with smooth camera movement and premium studio lighting",
"resolution": "480p",
"aspect_ratio": "auto",
"duration": 5,
"sound": 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-3-0-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": 1767965790929,
"costTime": 180000
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "UPSTREAM_ERROR",
"failMsg": "Generation failed",
"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 lake at sunrise with a slow cinematic camera move",
"resolution": "480p",
"aspect_ratio": "16:9",
"duration": 6,
"sound": true,
"watermark": false
}
}
```
### Image-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"prompt": "animate this portrait with subtle head movement and cinematic lighting",
"image_urls": [
"https://example.com/first-frame.png",
"https://example.com/last-frame.png"
],
"resolution": "720p",
"aspect_ratio": "auto",
"duration": 5,
"sound": true
}
}
```
### Reference-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "reference-to-video",
"prompt": "keep the subject identity and create a natural speaking video",
"image_urls": [
"https://example.com/person.png"
],
"video_urls": [
"https://example.com/motion-reference.mp4"
],
"file_urls": [
"https://example.com/profile.pdf"
],
"resolution": "720p",
"aspect_ratio": "auto",
"duration": -1,
"sound": true,
"watermark": false
}
}
```
## Parameters
Result delivery mode. Omit this field or use `async` for polling with `statusTask`, or use `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](/docs/api-reference/webhooks).
Wan 3.0 Video input parameters.
Generation mode. Supported values: `text-to-video`, `image-to-video`, `reference-to-video`.
Prompt text. Required for `text-to-video`; optional for `image-to-video` and `reference-to-video`. Required prompts cannot be empty after trimming.
Output resolution tier. Supported values: `480p`, `720p`, `1080p`.
Output aspect ratio. Supported values: `auto`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Use `aspect_ratio`, not `ratio`.
Output duration in seconds. Supports `-1` for smart duration, or integers from `2` through `30`, including numeric strings such as `"8"`. Decimal values such as `-1.0` are rejected.
Whether the generated video should include audio.
Whether to add a watermark.
Optional random seed. Supported range: `0` to `2147483647`. A fixed seed improves reproducibility, but identical seeds do not guarantee identical outputs.
Image URLs. Required for `image-to-video` with 1-2 images, where `image_urls[0]` is the first frame and `image_urls[1]` is the optional last frame. Optional for `reference-to-video` with up to 10 images.
Reference video URLs for `reference-to-video`. Supports up to 5 URLs when provided. Each video must be 1-15 seconds, total reference video duration cannot exceed 15 seconds, and reference video seconds are billed at the same per-second rate as the selected `mode` and `resolution`.
Reference audio URLs for `reference-to-video`. Supports up to 5 URLs when provided. Each audio file must be 1-15 seconds, and total reference audio duration cannot exceed 15 seconds. Audio is not billed separately.
File inputs for `reference-to-video`. Supports at most 1 URL. Cannot be used together with `link_urls`.
Web link inputs for `reference-to-video`. Supports at most 1 URL. Cannot be used together with `file_urls`.
| Mode | Required input | Unsupported media fields | Billing note |
| -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `text-to-video` | `prompt` | `image_urls`, `video_urls`, `audio_urls`, `file_urls`, `link_urls` | Output duration is billed per second. |
| `image-to-video` | `image_urls` with 1-2 images | `video_urls`, `audio_urls`, `file_urls`, `link_urls` | Output duration is billed per second. |
| `reference-to-video` | At least one of `image_urls`, `video_urls`, `audio_urls`, `file_urls`, or `link_urls` | None, but `file_urls` and `link_urls` are mutually exclusive | Output duration and reference video seconds are billed per second. |
Use public, directly accessible URLs for all media inputs. Video and audio durations are checked before the task is submitted.
When `duration` is positive and `video_urls` are provided, total reference video seconds plus `duration` cannot exceed 30 seconds. When `duration` is `-1`, the request uses smart duration and is pre-charged as 30 seconds.
## Response format
### Submit task response
`POST /generateTask/wan-3-0-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: `processing`, `success`, or `failed`.
JSON string containing generated video URLs in `resultUrls`. 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 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-3-0-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": "reference-to-video",
"prompt": "create a polished product video using the references",
"image_urls": [
"https://example.com/ref.png"
],
"resolution": "720p",
"aspect_ratio": "auto",
"duration": -1,
"sound": true
}
}'
```
The callback payload uses the same top-level shape as status polling with `code`, `message`, and `data`. Successful callbacks include the final `state` and `resultJson`. See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Wan 3.0 Video is billed per second. Unit price depends on both `mode` and `resolution`.
| Mode | Resolution | APIXO official price |
| -------------------- | ---------- | -------------------- |
| `text-to-video` | `480p` | `$0.075 / second` |
| `text-to-video` | `720p` | `$0.10 / second` |
| `text-to-video` | `1080p` | `$0.15 / second` |
| `image-to-video` | `480p` | `$0.075 / second` |
| `image-to-video` | `720p` | `$0.10 / second` |
| `image-to-video` | `1080p` | `$0.15 / second` |
| `reference-to-video` | `480p` | `$0.10 / second` |
| `reference-to-video` | `720p` | `$0.15 / second` |
| `reference-to-video` | `1080p` | `$0.24 / second` |
Billing formulas:
| Request | Formula |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text-to-video` or `image-to-video` with positive `duration` | `duration * unitPrice` |
| `reference-to-video` with positive `duration` | `(input video seconds + duration) * unitPrice` |
| Any mode with `duration = -1` | Pre-charge `30 * unitPrice`; after success, final billable seconds are `input video seconds + actual output seconds`, and any difference is refunded |
Input images, audio files, files, and links do not add separate billable seconds.
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Wan 3.0 Video tasks are asynchronous. Actual latency may vary by prompt complexity, duration, reference media accessibility, resolution, route queue load, and provider-side processing time.
| Workload | Typical generation time | Recommended first poll | Poll interval |
| ----------------------------------------------------------------- | ------------------------------------------ | --------------------------- | ------------- |
| Text-to-video or image-to-video | Varies by prompt, resolution, and duration | 60s after task creation | 10s-15s |
| Reference-to-video with image, video, audio, file, or link inputs | Often longer than simple generation | 60s-90s after task creation | 10s-15s |
For production workloads, use callback mode to avoid frequent polling while video tasks run.
Result URLs are temporary. Download and store important outputs promptly after task completion.
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](/docs/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `400` | Invalid request body, missing `input`, unsupported `mode`, missing required `prompt` or media, invalid `resolution`, invalid `aspect_ratio`, invalid `duration`, or invalid media array | 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 | Check permissions and route strategy |
| `404` | Task not found when polling | Check the `taskId` |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error or unknown task failure | Retry with backoff |
| `502` | Upstream error | Retry with backoff |
| `504` | Upstream timeout | Retry or use callback mode for long-running jobs |
### Validation notes
| Condition | Backend behavior |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Missing `input` | Request fails before task creation. |
| Missing `mode` | Request fails before task creation. |
| Unsupported `mode` | Request fails before task creation. Supported values are `text-to-video`, `image-to-video`, and `reference-to-video`. |
| Missing `prompt` in `text-to-video` | Request fails before task creation. |
| Empty required `prompt` | Request fails before task creation. |
| Missing `resolution` | Defaults to `1080p`. |
| Unsupported `resolution` | Request fails before task creation. Supported values are `480p`, `720p`, and `1080p`. |
| Missing `aspect_ratio` | Defaults to `auto`. |
| Unsupported `aspect_ratio` | Request fails before task creation. Use `auto`, `16:9`, `4:3`, `1:1`, `3:4`, or `9:16`. |
| Using `ratio` instead of `aspect_ratio` | `ratio` is not a public Wan 3.0 field. Use `aspect_ratio`. |
| Missing `duration` | Defaults to `5`. |
| `duration` outside `-1` or `2` through `30`, or a decimal value | Request fails before task creation. |
| `image-to-video` without `image_urls` | Request fails before task creation. |
| `image-to-video` with more than 2 images | Request fails before task creation. |
| `reference-to-video` without any reference input | Request fails before task creation. |
| `file_urls` and `link_urls` used together | Request fails before task creation. |
| Reference video or audio shorter than 1 second or longer than 15 seconds | Request fails before task creation. |
| Total reference video duration or total reference audio duration over 15 seconds | Request fails before task creation. |
| Positive `duration` plus total reference video duration over 30 seconds | Request fails before task creation. |
### Task failure codes
`failCode` is generated from APIXO's mapped provider error. Common values include:
| Fail code | Meaning | What to do |
| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| `SensitiveContent` | Prompt or input/output content was rejected by safety checks | Change the prompt or reference media |
| `PromptInvalid` | Prompt was invalid or rejected by the provider | Rewrite the prompt and retry |
| `ImageFormatIncorrect` | Reference image format could not be processed | Use a public, direct image URL in a common image format |
| `RateLimited` | Provider-side rate limit was reached | Retry with exponential backoff |
| `Timeout` | Provider-side timeout | Retry later or use callback mode |
| `Unknown error` | The provider returned an unmapped failure | Retry with backoff or contact support with the `taskId` |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/docs/models)
* [Video Models](/docs/models/video)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Routing Strategies](/docs/concepts/routing-strategies)
* [Try Wan 3.0 Video in the APIXO Playground](https://apixo.ai/models/wan-3-0-video)
* [Pricing](https://apixo.ai/pricing)