# Wan 3.0 Video (wan3.0-video)

Vendor: Alibaba
Model ID: `wan3.0-video`
Base URL: `https://api.mulerouter.ai`
Type: Inference API (async task-based)

## Description
Alibaba video generation from text, keyframes, reference images, videos, audio, files, or links; 480p/720p/1080p.

## Variant: Create Generation Task

Endpoint: `POST /vendors/alibaba/v1/w3.0-video/generation`

### Input Schema
The API accepts the following input parameters:

- **`file`** (`string | null`, _optional_):
  Reference file URL. HTTP/HTTPS only; at most one file. Supported formats: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md. Maximum size is 100MB. The upstream specification limits PDF, DOCX, DOC, PPTX, PPT, KEY, and PAGES files to 50 pages. Mutually exclusive with `link` and keyframe-mode fields.
  - Default: `null`

- **`link`** (`string | null`, _optional_):
  Public web page URL. HTTP/HTTPS only; the page must be accessible without authentication. At most one link. Mutually exclusive with `file` and keyframe-mode fields.
  - Default: `null`

- **`seed`** (`integer | null`, _optional_):
  Random seed [0, 2147483647]. null or omitted for an auto-generated seed.
  - Default: `null`

- **`audio`** (`boolean`, _optional_):
  Whether the output video includes an audio track. Pricing is identical either way.
  - Default: `true`

- **`ratio`** (`string`, _optional_):
  Aspect ratio (case-insensitive). `adaptive` derives the ratio from intent and input media.
  - Options: `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"adaptive"`
  - Default: `"adaptive"`

- **`prompt`** (`string | null`, _optional_):
  Text prompt describing the desired video. Up to 20000 characters — over-length prompts are not rejected, they are passed through and truncated upstream. Required unless a keyframe or reference input is given.
  - Default: `null`

- **`duration`** (`integer`, _optional_):
  Video duration in seconds, 2–30 inclusive, or `-1` for smart duration (upstream picks the length from intent / content / media). With video input, the combined input + output duration must be ≤30s — validated upstream.
  - Options: `-1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`
  - Default: `5`

- **`last_frame`** (`string | null`, _optional_):
  Last-frame image, strictly used as the last frame of the video. Same input formats and upstream constraints as `first_frame`. Keyframe mode; cannot be combined with reference-mode fields.
  - Default: `null`

- **`resolution`** (`string`, _optional_):
  Output resolution (case-insensitive). 2k / 4k require `w3.0-video-pro`.
  - Options: `"480p"`, `"720p"`, `"1080p"`
  - Default: `"1080p"`

- **`first_frame`** (`string | null`, _optional_):
  First-frame image, strictly used as the first frame of the video. Accepts a public HTTP/HTTPS URL, a `data:image/<type>;base64,...` data URI, or a bare Base64 string. Keyframe mode; cannot be combined with reference-mode fields.  Upstream format requirements (validated upstream, not by this gateway): JPEG/JPG/PNG (no alpha)/BMP/WEBP, side 240–8000px, ratio ≤8:1, ≤20MB.
  - Default: `null`

- **`prompt_extend`** (`boolean`, _optional_):
  Whether upstream rewrites (expands) the prompt before generation. Enabled by default: rewriting usually improves motion and cinematography on short prompts. Set to `false` to keep generation close to the literal prompt text.
  - Default: `true`

- **`reference_audios`** (`array | null`, _optional_):
  Reference audios, up to 5, total duration ≤15s. URL only — Base64 is not accepted here. Reference mode; cannot be combined with keyframe fields.  Upstream format requirements: wav/mp3, each 1–15s, ≤15MB. This gateway checks only the recognizable file extension (`.wav` / `.mp3`); extensionless URLs are passed through.
  - Default: `null`

- **`reference_images`** (`array | null`, _optional_):
  Reference images, up to 10. Each item accepts a public HTTP/HTTPS URL, a `data:image/<type>;base64,...` data URI, or a bare Base64 string; the three shapes may be mixed within one array. Referenced in `prompt` as "Image 1", "Image 2", … in array order. Reference mode; cannot be combined with keyframe fields.  Upstream format requirements: JPEG/JPG/PNG (no alpha)/BMP/WEBP, side 240–8000px, ratio ≤8:1, ≤20MB.
  - Default: `null`

- **`reference_videos`** (`array | null`, _optional_):
  Reference videos, up to 5, total duration ≤15s. URL only — Base64 is not accepted here (a 100MB video would inflate the request body to ~133MB). Referenced in `prompt` as "Video 1", "Video 2", … in array order. Reference mode; cannot be combined with keyframe fields.  Upstream format requirements: mp4/mov, side 240–4096px, ratio ≤8:1, each 1–15s, ≤100MB. This gateway checks only the recognizable file extension (`.mp4` / `.mov`); extensionless URLs such as signed links are passed through.
  - Default: `null`

**Full Example**:

```json
{
  "file": null,
  "link": null,
  "seed": null,
  "audio": true,
  "ratio": "adaptive",
  "prompt": null,
  "duration": 5,
  "last_frame": null,
  "resolution": "1080p",
  "first_frame": null,
  "prompt_extend": true,
  "reference_audios": null,
  "reference_images": null,
  "reference_videos": null
}
```

### Output Schema
The API returns the following output format:

- **`task_info`** (`object`, _optional_):

  - **`id`** (`string (uuid)`, _required_):
    UUID of the task

  - **`status`** (`string`, _required_):
    Task status (pending when created)
    - Options: `"pending"`

  - **`created_at`** (`string (date-time)`, _required_):
    Task creation timestamp (ISO 8601)

  - **`updated_at`** (`string (date-time)`, _required_):
    Task last update timestamp (ISO 8601)

**Example Response**:

```json
{
  "task_info": {}
}
```

## Variant: /vendors/alibaba/v1/w3.0-video/generation/{task_id}

Endpoint: `POST /vendors/alibaba/v1/w3.0-video/generation/{task_id}`

## Usage (Async Task API)
This model uses an async task-based workflow with two API calls:
1. **Submit a task** — `POST /v1/inference/wan3.0-video` to create a generation task
2. **Poll for result** — `GET /v1/inference/wan3.0-video/{task_id}` to check status and retrieve the result

### Step 1: Submit a Task

#### cURL
```bash
curl -X POST https://api.mulerouter.ai/vendors/alibaba/v1/w3.0-video/generation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_MULEROUTER_API_KEY>" \
  -d '{
    "prompt": "Your prompt here"
  }'
```

#### Python
```python
import requests

API_KEY = "<YOUR_MULEROUTER_API_KEY>"
ENDPOINT = "https://api.mulerouter.ai/vendors/alibaba/v1/w3.0-video/generation"

response = requests.post(
    ENDPOINT,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    },
    json={
        "prompt": "Your prompt here"
    }
)

result = response.json()
task_id = result["task_info"]["id"]
print(f"Task created: {task_id}")
```

#### Node.js / TypeScript
```typescript
const API_KEY = "<YOUR_MULEROUTER_API_KEY>";
const ENDPOINT = "https://api.mulerouter.ai/vendors/alibaba/v1/w3.0-video/generation";

const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
        prompt: "Your prompt here"
    })
});

const result = await response.json();
const taskId = result.task_info.id;
console.log("Task created:", taskId);
```

#### Submit Response (202)
```json
{
  "task_info": {
    "id": "8e1e315e-b50d-4334-a231-be7d19a372f4",
    "status": "processing",
    "created_at": "2026-01-01T00:00:00.000Z"
  }
}
```

### Step 2: Poll for Result

Use the task ID from Step 1 to poll the status endpoint until the task is completed.

Endpoint: `GET /v1/inference/wan3.0-video/{task_id}`

#### cURL
```bash
curl -X GET https://api.mulerouter.ai/vendors/alibaba/v1/w3.0-video/generation/<TASK_ID> \
  -H "Authorization: Bearer <YOUR_MULEROUTER_API_KEY>"
```

#### Python
```python
import time

status_url = f"https://api.mulerouter.ai/vendors/alibaba/v1/w3.0-video/generation/{task_id}"

while True:
    status = requests.get(status_url, headers={
        "Authorization": f"Bearer {API_KEY}"
    }).json()
    task_status = status["task_info"]["status"]
    if task_status in ("completed", "succeeded"):
        print("Result:", status)
        break
    elif task_status == "failed":
        print("Task failed:", status)
        break
    time.sleep(5)
```

#### Node.js / TypeScript
```typescript
const statusUrl = `https://api.mulerouter.ai/vendors/alibaba/v1/w3.0-video/generation/${taskId}`;

while (true) {
    const statusRes = await fetch(statusUrl, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    const status = await statusRes.json();
    const taskStatus = status.task_info.status;
    if (taskStatus === "completed" || taskStatus === "succeeded") {
        console.log("Result:", status);
        break;
    } else if (taskStatus === "failed") {
        console.log("Task failed:", status);
        break;
    }
    await new Promise(r => setTimeout(r, 5000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://www.mulerouter.ai/models/wan3.0-video)
- [API Documentation](https://www.mulerouter.ai/docs/api-reference/endpoint/alibaba/w3.0-video/generation)

### MuleRouter Platform

- [Platform Documentation](https://www.mulerouter.ai/docs)
- [API Keys Management](https://www.mulerouter.ai/app/api-keys)