> ## 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.7 Video
> Alibaba video generation and editing API for text, image, reference, and video-edit workflows
## Overview
Wan 2.7 Video is an Alibaba video model for text-to-video, image-to-video, reference-guided generation, and video editing. 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-7-video` |
| Modes | `text-to-video`, `image-to-video`, `reference-to-video`, `video-edit` |
| Prompt | Required for `text-to-video`, `reference-to-video`, and `video-edit`; optional for `image-to-video` |
| Resolutions | `720p`, `1080p` |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` |
| Mode-specific ratio rules | Default `16:9` for `text-to-video` and `reference-to-video`; not supported for `image-to-video`; optional for `video-edit` |
| Duration | `text-to-video`/`image-to-video`: `2-15` (default `5`); `reference-to-video`: `2-15` or `2-10` when any reference video is used (default `5`); `video-edit`: `0` or `2-10` (default `0`) |
| Public media fields | `image_urls`, `video_urls`, `audio_urls` |
## Public input contract
* Public media input fields are `image_urls`, `video_urls`, and `audio_urls`.
* Use `audio_urls` for audio input.
* For `reference-to-video`, `audio_urls` aligns by slot order: first `image_urls`, then `video_urls`.
* For `reference-to-video`, use empty string `""` in `audio_urls` to skip a specific reference slot without shifting later audio bindings.
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/wan-2-7-video` | Submit a generation or edit task |
| `GET` | `/statusTask/wan-2-7-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-2-7-video" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-video",
"prompt": "a cinematic rainy night in tokyo",
"resolution": "1080p",
"ratio": "16:9",
"duration": 5
}
}'
```
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-7-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": 1767965652317,
"costTime": 41388
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "PromptInvalid",
"failMsg": "Prompt is invalid or rejected by provider",
"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 cinematic rainy night in tokyo",
"audio_urls": [
"https://example.com/background.mp3"
],
"negative_prompt": "blurry, low quality",
"resolution": "1080p",
"ratio": "16:9",
"duration": 8,
"prompt_extend": true,
"watermark": false,
"seed": 12345
}
}
```
### Image-to-video (first and optional last frame)
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-video",
"image_urls": [
"https://example.com/first-frame.png",
"https://example.com/last-frame.png"
],
"audio_urls": [
"https://example.com/driving-audio.mp3"
],
"prompt": "smooth camera motion with gentle wind",
"resolution": "720p",
"duration": 6
}
}
```
### Reference-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "reference-to-video",
"prompt": "keep character style and outfit consistency, but only image 1 should speak",
"image_urls": [
"https://example.com/ref-1.png"
],
"video_urls": [
"https://example.com/ref-clip.mp4"
],
"audio_urls": [
"https://example.com/ref-voice-1.mp3",
""
],
"resolution": "1080p",
"ratio": "16:9",
"duration": 6
}
}
```
### Video-edit
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "video-edit",
"video_urls": [
"https://example.com/input.mp4"
],
"image_urls": [
"https://example.com/reference.png"
],
"prompt": "change the style into clay animation",
"negative_prompt": "blurry, low quality",
"resolution": "720p",
"ratio": "1:1",
"duration": 0,
"audio_setting": "auto",
"prompt_extend": true,
"watermark": false
}
}
```
## 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.7 Video input parameters.
Generation mode. Supported values: `text-to-video`, `image-to-video`, `reference-to-video`, `video-edit`.
Prompt text. Required for `text-to-video`, `reference-to-video`, and `video-edit`. Optional for `image-to-video`. Required prompts cannot be empty after trimming. Supports Chinese and English; maximum length is `5000` characters and excess content is truncated.
Optional negative prompt. Supports Chinese and English; maximum length is `500` characters and excess content is truncated.
Output resolution tier. Supported values: `720p`, `1080p`.
Supported values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`. Default is `16:9` for `text-to-video` and `reference-to-video`. Not supported for `image-to-video`. Optional for `video-edit`.
Accepts integer or numeric string input. `text-to-video` and `image-to-video`: `2-15` (default `5`). `reference-to-video`: `2-15` by default, but `2-10` when any reference video is provided (default `5`). `video-edit`: `0` or `2-10` (default `0`).
Whether to enable prompt rewriting before generation. `true` (default) enables rewriting and can improve short prompts but may increase latency. `false` disables rewriting.
Whether to add a watermark. `false` (default) means no watermark. `true` adds a bottom-right watermark with fixed text `AI 生成`.
Optional random seed. Supported range: `0` to `2147483647`. A fixed seed improves reproducibility, but identical seeds do not guarantee identical outputs.
Public image URLs. `image-to-video`: use `1-2` images when no `video_urls` are provided (first frame, plus optional last frame), or at most `1` image as last frame when `video_urls` is present. `reference-to-video`: optional `1-5` images, but total `image_urls + video_urls` must be `1-5`. `video-edit`: optional `1-4` reference images. Image constraints: formats `JPEG/JPG/PNG` (no alpha), `BMP`, `WEBP`; width and height `240-8000` px; aspect ratio `1:8-8:1`; file size `<= 20MB`.
Public video URLs. `image-to-video`: optional `1` continuation clip at `video_urls[0]`. `reference-to-video`: optional `1-5` reference videos, with total `image_urls + video_urls` between `1` and `5`. `video-edit`: required and must contain exactly `1` input video URL. Video constraints by mode: `image-to-video` continuation clip (`video_urls[0]`) must be `mp4/mov`, `2-10s`, `240-4096` px, ratio `1:8-8:1`, size `<= 100MB`; `reference-to-video` reference video must be `mp4/mov`, `1-30s`, `240-4096` px, ratio `1:8-8:1`, size `<= 100MB`; `video-edit` input video must be `mp4/mov`, `2-10s`, `240-4096` px, ratio `1:8-8:1`, size `<= 100MB`.
Public audio URLs. `text-to-video`: optional `1` background audio URL. `image-to-video`: optional `1` driving audio URL, and only when `video_urls` is not provided. `reference-to-video`: optional `1-5`, aligned by slot order to reference items (`image_urls` first, then `video_urls`). Length can be less than the total reference count, but cannot exceed `image_urls + video_urls`. To skip a reference slot while keeping later alignment, pass empty string `""` at that position. Non-empty values are mapped as per-reference voice. If no `audio_urls` are provided for `reference-to-video`, reference videos can keep their original voice by default. Audio constraints: formats `wav/mp3`, duration `2-30s`, size `<= 15MB`. If audio is longer than `duration`, truncates to the first `duration` seconds; if shorter, the remaining video segment is silent.
`video-edit` only. Supported values: `auto`, `origin`. `auto` (default) lets decide whether to regenerate audio based on prompt sound instructions, otherwise it may keep original audio. `origin` forces original input audio and skips regeneration.
## Response format
### Submit task response
`POST /generateTask/wan-2-7-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 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 upstream timing 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-7-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": "video-edit",
"video_urls": [
"https://example.com/input.mp4"
],
"image_urls": [
"https://example.com/reference.png"
],
"prompt": "change the scene to watercolor style",
"resolution": "1080p",
"duration": 0,
"audio_setting": "origin"
}
}'
```
See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Wan 2.7 Video is billed per second. Unit price depends on both `mode` and `resolution`.
| Mode | Resolution | APIXO official price |
| -------------------- | ---------- | -------------------- |
| `text-to-video` | `720p` | `$0.10 / second` |
| `text-to-video` | `1080p` | `$0.15 / second` |
| `image-to-video` | `720p` | `$0.10 / second` |
| `image-to-video` | `1080p` | `$0.15 / second` |
| `reference-to-video` | `720p` | `$0.15 / second` |
| `reference-to-video` | `1080p` | `$0.24 / second` |
| `video-edit` | `720p` | `$0.10 / second` |
| `video-edit` | `1080p` | `$0.15 / second` |
Billing formulas:
| Mode | Formula |
| -------------------- | ----------------------------- |
| `text-to-video` | `duration * unitPrice` |
| `image-to-video` | `duration * unitPrice` |
| `reference-to-video` | `duration * unitPrice` |
| `video-edit` | `billableSeconds * unitPrice` |
For `video-edit`, billing is based on both input and output duration:
* Input video duration must be between 2 and 10 seconds (inclusive).
* Billable input duration is capped at `10` seconds.
* If `duration = 0`, then `billableSeconds = cappedInputDuration * 2`.
* If `duration = 2-10`, then `billableSeconds = cappedInputDuration + duration`.
* Maximum billable seconds for `video-edit` is `20`.
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Wan 2.7 Video tasks are asynchronous. The backend does not provide a fixed public latency SLA; actual latency varies by mode, resolution, duration, prompt complexity, media fetch speed, and provider queue load.
| Workflow | Recommended first poll | Poll interval |
| -------------------- | --------------------------- | ------------- |
| `text-to-video` | 60s after task creation | 10s |
| `image-to-video` | 60s after task creation | 10s |
| `reference-to-video` | 60s-90s after task creation | 10s-15s |
| `video-edit` | 60s-90s after task creation | 10s-15s |
For production workloads, use callback mode to avoid frequent polling on long-running video jobs.
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 route cannot access the model | Check permissions and route strategy |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error | Retry with backoff |
| `502` | Upstream provider error | Retry with backoff |
| `504` | Upstream timeout | Retry or use callback mode |
### Task failure codes
`failCode` is route-dependent and may come from mapped upstream failures. Common values include:
| Fail code | Meaning | What to do |
| ----------------------------------------------- | -------------------------------------------------- | --------------------------------------------------- |
| `PromptInvalid` | Prompt is invalid or rejected by provider | Rewrite prompt and retry |
| `MissingParameter` / `BadRequest` | Required fields are missing or malformed | Check mode-specific required fields |
| `SensitiveContent` / `SensitiveContentDetected` | Prompt or media failed safety checks | Change prompt or media |
| `RateLimitExceeded` | Provider or route rate limit was reached | Retry with backoff |
| `Task TimeOut` / `Timeout` | Upstream generation timed out | Retry or use callback mode |
| `UnmappedUpstreamError` | Upstream error could not be mapped to a known type | Retry with backoff or contact support with `taskId` |
### Parameter troubleshooting
* `mode` must be one of `text-to-video`, `image-to-video`, `reference-to-video`, `video-edit`.
* `prompt` is required for `text-to-video`, `reference-to-video`, and `video-edit`.
* `ratio` is not allowed in `image-to-video`.
* `image-to-video` requires `image_urls` or `video_urls`.
* If `image-to-video` includes `video_urls`, `audio_urls` is not allowed.
* `reference-to-video` requires at least one reference item across `image_urls` and `video_urls`, with total count `<= 5`.
* If `reference-to-video` includes `audio_urls`, it binds by slot order: `image_urls` first, then `video_urls`.
* If `reference-to-video` needs to skip a reference slot while keeping later audio aligned, pass empty string `""` in that slot.
* If `reference-to-video` includes `audio_urls`, its length cannot exceed `image_urls + video_urls`.
* `video-edit` requires exactly one `video_urls` item.
* `video-edit` requires a non-empty `prompt`.
* `video-edit` input clip duration must be `2-10` seconds.
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)