> ## 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 全能視頻生成

> 使用 Wan 3.0 All-in-One 模型生成視頻，支持文生視頻、首尾幀控制和圖片、視頻、音頻等多模態參考

<Note>
  **中國大陸用戶請注意：** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址（Base URL）。文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`。
</Note>

Wan 3.0 的公共模型名為 `wan3.0-video`。同一個模型支持以下生成方式：

* 文生視頻
* 首幀或首尾幀控制
* 參考圖片、參考視頻和參考音頻聯合生成
* 文件或公開網頁內容參考

接口為異步任務。提交成功後返回任務 ID，再通過[視頻任務狀態接口](../../tasks/video-status)查詢進度和結果。

<Warning>
  **首尾幀模式與參考素材模式互斥。**

  只要請求中包含 `first_frame` 或 `last_frame`，就不能同時傳入參考圖片、參考視頻、參考音頻、文件或網頁連結。參考圖片、參考視頻和參考音頻之間可以組合使用。
</Warning>

## 認證

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 認證：

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

## 請求參數

<ParamField body="model" type="string" default="wan3.0-video" required>
  模型名稱，固定為 `wan3.0-video`。
</ParamField>

<ParamField body="prompt" type="string">
  視頻內容、主體動作、鏡頭和聲音描述。`prompt` 與媒體素材至少提供一項。

  使用多模態參考時，可以按數組順序在提示詞中寫「圖片1」「視頻1」「音頻1」。
</ParamField>

<ParamField body="duration" type="integer" default="5">
  輸出時長，支持 `2` 至 `30` 秒；傳 `-1` 為智能時長，由模型根據提示詞和素材自動決定輸出長度。
</ParamField>

<ParamField body="ratio" type="string" default="adaptive">
  輸出寬高比，支持：

  * `adaptive`，根據參考素材自適應
  * `16:9`
  * `9:16`
  * `1:1`
  * `4:3`
  * `3:4`

  兼容字段 `aspect_ratio` 也可以使用。無需同時傳入兩個字段。
</ParamField>

<ParamField body="resolution" type="string" default="1080p">
  輸出分辨率，支持 `480p`、`720p` 和 `1080p`。
</ParamField>

<ParamField body="audio" type="boolean" default={true}>
  是否生成音頻，默認開啟。
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  是否添加水印，默認關閉。
</ParamField>

<ParamField body="seed" type="integer">
  可選隨機種子。相同參數和種子有助於復現相近結果。
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  首尾幀控制數組。每項包含：

  * `url`：公開可訪問的圖片 URL
  * `role`：`first_frame` 或 `last_frame`

  最多提供一個首幀和一個尾幀。使用 `last_frame` 時必須同時提供 `first_frame`。
</ParamField>

<ParamField body="reference_images" type="string[]">
  參考圖片 URL 數組，最多 `10` 張。不能與 `image_with_roles` 中的首尾幀混用。
</ParamField>

<ParamField body="video_list" type="object[]">
  參考視頻數組，最多 `5` 段，總時長不超過 `15` 秒。每項使用以下結構：

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

<ParamField body="audio_with_roles" type="object[]">
  參考音頻數組，最多 `5` 段，總時長不超過 `15` 秒。每項包含：

  * `url`：公開可訪問的音頻 URL
  * `role`：固定為 `reference_audio`
</ParamField>

<ParamField body="metadata" type="object">
  文件或網頁參考通過 `metadata.media` 傳入。

  <Expandable title="展開 metadata.media 結構">
    `media` 是對象數組，每項包含 `type` 和 `url`：

    * 文件：`{ "type": "file", "url": "https://example.com/brief.pdf" }`
    * 網頁：`{ "type": "link", "url": "https://example.com/article" }`

    單次請求最多提供一個文件或一個網頁，二者不能同時使用。文件和網頁也不能與首尾幀模式混用。
  </Expandable>
</ParamField>

<Note>
  本地圖片或視頻需要先上傳並取得公開 URL。不要在生成請求中直接傳入本地文件路徑或 base64 數據。
</Note>

## 素材組合規則

| 請求內容 | 是否支持 | 說明 |
| - | -: | - |
| 僅提示詞 | 是 | 文生視頻 |
| 僅首幀 | 是 | 首幀控制 |
| 首幀和尾幀 | 是 | 尾幀不能單獨使用 |
| 參考圖片和參考視頻 | 是 | 可聯合參考 |
| 參考圖片、視頻和音頻 | 是 | 可聯合參考 |
| 首幀和參考視頻 | 否 | 首尾幀模式與參考素材模式互斥 |
| 首尾幀和參考圖片 | 否 | 首尾幀模式與參考素材模式互斥 |
| 文件和網頁連結 | 否 | 兩者互斥 |

如果收到以下錯誤：

```text theme={null}
Wan 3.0 不能在同一請求中混用首尾幀與參考素材/文件/網頁。
```

請刪除首幀/尾幀，保留參考素材；或者刪除全部參考素材，只保留首幀/尾幀。

## 請求示例

### 文生視頻

```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": "一隻橘貓在雨後的東京街道奔跑，電影感運鏡",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p",
    "audio": true,
    "watermark": false
  }'
```

### 首尾幀生成視頻

```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": "鏡頭自然推進，人物從站立狀態過渡到微笑揮手",
    "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"
      }
    ]
  }'
```

### 參考視頻生成視頻

不要在此請求中同時傳入 `first_frame` 或 `last_frame`。

```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": "參考視頻1的運鏡和人物動作，生成一段新的街舞視頻",
    "duration": 10,
    "ratio": "adaptive",
    "resolution": "720p",
    "audio": true,
    "video_list": [
      {
        "video_url": "https://example.com/reference-video.mp4"
      }
    ]
  }'
```

### 圖片、視頻和音頻聯合參考

```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": "使用圖片1中的人物形象、視頻1中的動作和音頻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"
      }
    ]
  }'
```

### 文件參考

```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": "根據文件內容生成一段簡潔的產品介紹視頻",
    "duration": 10,
    "ratio": "16:9",
    "resolution": "1080p",
    "metadata": {
      "media": [
        {
          "type": "file",
          "url": "https://example.com/product-brief.pdf"
        }
      ]
    }
  }'
```

## 響應

<ResponseField name="id" type="string">
  視頻任務 ID，用於查詢任務狀態。
</ResponseField>

<ResponseField name="object" type="string">
  對象類型，通常為 `generation.task`。
</ResponseField>

<ResponseField name="model" type="string">
  本次請求使用的模型名稱。
</ResponseField>

<ResponseField name="status" type="string">
  任務狀態：`queued`、`in_progress`、`completed` 或 `failed`。
</ResponseField>

<ResponseField name="progress" type="integer">
  任務進度，範圍為 `0` 至 `100`。
</ResponseField>

<ResponseField name="created_at" type="integer">
  任務創建時間戳。
</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.