> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wan 3.0 All-in-One Video Generation

> Generate videos with the Wan 3.0 All-in-One model — supports text-to-video, first/last-frame control, and multimodal references including images, video, and audio

<Note>
  **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.
</Note>

The public model name for Wan 3.0 is `wan3.0-video`. A single model supports the following generation modes:

* Text-to-video
* First-frame or first/last-frame control
* Joint generation with reference images, reference videos, and reference audio
* File or public web page references

The API is asynchronous. A successful submission returns a task ID; use the [Video Task Status](../../tasks/video-status) endpoint to query progress and results.

<Warning>
  **First/last-frame mode and reference-asset mode are mutually exclusive.**

  If the request contains `first_frame` or `last_frame`, you cannot also pass reference images, reference videos, reference audio, files, or web links. Reference images, reference videos, and reference audio can be combined with each other.
</Warning>

## Authentication

<ParamField header="Authorization" type="string" required>
  Use Bearer Token authentication:

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Request Parameters

<ParamField body="model" type="string" default="wan3.0-video" required>
  Model name, fixed as `wan3.0-video`.
</ParamField>

<ParamField body="prompt" type="string">
  Description of the video content, subject motion, camera work, and sound. At least one of `prompt` or media assets must be provided.

  When using multimodal references, you can write "image 1", "video 1", "audio 1" in the prompt, matching the array order.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Output duration, supports `2` to `30` seconds. Pass `-1` for smart duration to let the model decide the output length automatically.
</ParamField>

<ParamField body="ratio" type="string" default="adaptive">
  Output aspect ratio, supports:

  * `adaptive`, adapts to reference assets
  * `16:9`
  * `9:16`
  * `1:1`
  * `4:3`
  * `3:4`

  The compatible field `aspect_ratio` can also be used. Do not pass both fields.
</ParamField>

<ParamField body="resolution" type="string" default="1080p">
  Output resolution, supports `480p`, `720p`, and `1080p`.
</ParamField>

<ParamField body="audio" type="boolean" default={true}>
  Whether to generate audio. Enabled by default.
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  Whether to add a watermark. Disabled by default.
</ParamField>

<ParamField body="seed" type="integer">
  Optional random seed. The same parameters and seed help reproduce similar results.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  First/last-frame control array. Each item contains:

  * `url`: publicly accessible image URL
  * `role`: `first_frame` or `last_frame`

  Provide at most one first frame and one last frame. `last_frame` requires `first_frame` to be provided as well.
</ParamField>

<ParamField body="reference_images" type="string[]">
  Array of reference image URLs, up to `10` images. Cannot be mixed with first/last frames in `image_with_roles`.
</ParamField>

<ParamField body="video_list" type="object[]">
  Array of reference videos, up to `5` clips with a total duration not exceeding `15` seconds. Each item uses the following structure:

  ```json theme={null}
  {
    "video_url": "https://example.com/reference.mp4"
  }
  ```
</ParamField>

<ParamField body="audio_with_roles" type="object[]">
  Array of reference audio, up to `5` clips with a total duration not exceeding `15` seconds. Each item contains:

  * `url`: publicly accessible audio URL
  * `role`: fixed as `reference_audio`
</ParamField>

<ParamField body="metadata" type="object">
  File or web page references are passed via `metadata.media`.

  <Expandable title="Show metadata.media structure">
    `media` is an array of objects, each containing `type` and `url`:

    * File: `{ "type": "file", "url": "https://example.com/brief.pdf" }`
    * Web page: `{ "type": "link", "url": "https://example.com/article" }`

    A single request accepts at most one file or one web page — they cannot be used together. Files and web pages also cannot be mixed with first/last-frame mode.
  </Expandable>
</ParamField>

<Note>
  Local images or videos must be uploaded first to obtain a public URL. Do not pass local file paths or base64 data directly in the generation request.
</Note>

## Asset Combination Rules

| Request content | Supported | Notes |
| - | -: | - |
| Prompt only | Yes | Text-to-video |
| First frame only | Yes | First-frame control |
| First and last frame | Yes | Last frame cannot be used alone |
| Reference images and reference videos | Yes | Can be combined |
| Reference images, videos, and audio | Yes | Can be combined |
| First frame and reference video | No | First/last-frame mode and reference-asset mode are mutually exclusive |
| First/last frames and reference images | No | First/last-frame mode and reference-asset mode are mutually exclusive |
| File and web link | No | Mutually exclusive |

If you receive the following error:

```text theme={null}
Wan 3.0 cannot mix first/last frames with reference assets/files/web pages in the same request.
```

Remove the first/last frames and keep the reference assets; or remove all reference assets and keep only the first/last frames.

## Request Examples

### Text-to-Video

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan3.0-video",
    "prompt": "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p",
    "audio": true,
    "watermark": false
  }'
```

### First/Last-Frame Video

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan3.0-video",
    "prompt": "The camera pushes in naturally as the person transitions from standing to smiling and waving",
    "duration": 8,
    "ratio": "adaptive",
    "resolution": "1080p",
    "image_with_roles": [
      {
        "url": "https://example.com/first-frame.png",
        "role": "first_frame"
      },
      {
        "url": "https://example.com/last-frame.png",
        "role": "last_frame"
      }
    ]
  }'
```

### Reference-Video Generation

Do not pass `first_frame` or `last_frame` in this request.

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan3.0-video",
    "prompt": "Use the camera work and movements from video 1 to generate a new street dance video",
    "duration": 10,
    "ratio": "adaptive",
    "resolution": "720p",
    "audio": true,
    "video_list": [
      {
        "video_url": "https://example.com/reference-video.mp4"
      }
    ]
  }'
```

### Combined Image, Video, and Audio Reference

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan3.0-video",
    "prompt": "Generate a video using the character from image 1, the motion from video 1, and the rhythm of audio 1",
    "duration": 10,
    "ratio": "16:9",
    "resolution": "720p",
    "audio": true,
    "reference_images": [
      "https://example.com/character.png"
    ],
    "video_list": [
      {
        "video_url": "https://example.com/motion.mp4"
      }
    ],
    "audio_with_roles": [
      {
        "url": "https://example.com/music.mp3",
        "role": "reference_audio"
      }
    ]
  }'
```

### File Reference

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan3.0-video",
    "prompt": "Generate a concise product introduction video based on the file content",
    "duration": 10,
    "ratio": "16:9",
    "resolution": "1080p",
    "metadata": {
      "media": [
        {
          "type": "file",
          "url": "https://example.com/product-brief.pdf"
        }
      ]
    }
  }'
```

## Response

<ResponseField name="id" type="string">
  Video task ID, used to query task status.
</ResponseField>

<ResponseField name="object" type="string">
  Object type, usually `generation.task`.
</ResponseField>

<ResponseField name="model" type="string">
  Model name used for this request.
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Task progress, ranging from `0` to `100`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Task creation timestamp.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "tsk_vid_xxx",
    "object": "generation.task",
    "model": "wan3.0-video",
    "status": "in_progress",
    "progress": 10,
    "created_at": 1781577600
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.