# Wan 3.0 (https://wanapi.app/zh-tw/docs/wan-3-0)





Wan 3.0 支援文字、圖片與參考媒體輸入，可輸出 480p、720p 或 1080p 影片。此端點適用於標準版模型；選擇 1080p 不會切換至 Pro。[模型詳情與 Playground](/zh-tw/models/wan-3-0)。

## 連接 Wan API [#連接-wan-api]

使用 `https://api.wanapi.app` 作為 API 基底 URL。在 [API 金鑰設定](/zh-tw/settings/apikeys)建立金鑰，並以 `Authorization: Bearer YOUR_API_KEY` 傳送。請將金鑰保存在伺服器端。Playground 使用您的網站登入工作階段，費用從同一帳號的餘額扣除，不需要將金鑰貼入瀏覽器。

使用服務需要已啟用且餘額充足的帳號。目前費率請見[價格頁](/zh-tw/pricing)。各款模型都有獨立端點與[模型頁面](/zh-tw/models)。

`GET /v1/models` 會列出您的金鑰可使用的模型。選擇較高解析度不會自動切換模型。

| 設定           | Wan 3.0                                                         |
| ------------ | --------------------------------------------------------------- |
| 模型 ID        | `wan3.0-video`                                                  |
| `resolution` | `480p`, `720p`, `1080p`；預設值：`1080p`。                            |
| `duration`   | 輸出長度為 2–30 秒，或使用 `-1` 自動決定長度；預設值：`5`。                           |
| `ratio`      | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`；預設值：`adaptive`。 |
| `audio`      | 預設值為 `true`。設為 `false` 不會降低費率。                                  |

[共用請求欄位](#請求欄位)說明全部 14 個原生欄位、媒體限制與輸入組合。此模型在原生請求的 URL 中使用 `wan3.0-video`，在 [Responses 請求](#同步與背景-responses)中也以此作為 `model` 的值。

## 送出 Wan 3.0 任務 [#送出-wan-30-任務]

以下範例以此模型支援的最低解析度，送出 2 秒的文字轉影片請求。請在伺服器上將 `WAN_API_KEY` 設為您的金鑰。模型透過 URL 選擇，請勿在此原生 JSON 主體中加入 `model` 欄位。

```bash
curl https://api.wanapi.app/wan/v1/wan3.0-video/generation \
  -H "Authorization: Bearer $WAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A blue ball rolls across a white table. Static camera.",
    "duration": 2,
    "resolution": "480p",
    "ratio": "16:9",
    "audio": false,
    "prompt_extend": false
  }'
```

## 查詢 Wan 3.0 任務 [#查詢-wan-30-任務]

將回傳的 `task_info.id` 儲存為 `TASK_ID`，再查詢同一模型的端點。提交回應表示已收到任務，並非已完成的影片。請先以 5 秒為間隔輪詢；詳見[任務狀態與下載](#輪詢並下載影片)。

```bash
curl "https://api.wanapi.app/wan/v1/wan3.0-video/generation/$TASK_ID" \
  -H "Authorization: Bearer $WAN_API_KEY"
```

## Wan 3.0 價格 [#wan-30-價格]

下表列出目前的美元費率，以計費秒數計價。參考影片輸入秒數與生成輸出秒數均計入費用。5 秒範例以未使用參考影片為前提。款項預留與結算方式請見[計費與失敗處理](#計費與失敗處理)。

<WanModelPricing model="findWanModel('wan-3-0')" />

[查看 Wan 3.0 價格](/zh-tw/models/wan-3-0#pricing)。

## 請求欄位 [#請求欄位]

四款模型共用以下 14 個原生欄位。請提供提示詞或至少一項媒體輸入。影格輸入不能與參考輸入、`file` 或 `link` 併用；`file` 與 `link` 也不能同時使用。

| 欄位                 | 型別        | 規範                                                              |
| ------------------ | --------- | --------------------------------------------------------------- |
| `prompt`           | string    | 最多 20,000 個字元。                                                  |
| `first_frame`      | string    | 圖片 HTTP(S) URL、圖片 data URI 或 Base64。                            |
| `last_frame`       | string    | 圖片 HTTP(S) URL、圖片 data URI 或 Base64。                            |
| `reference_images` | string\[] | 最多 10 張圖片，可使用與影格相同的輸入形式。                                        |
| `reference_videos` | string\[] | 最多 5 個公開的 MP4/MOV URL；每支影片長度為 1–15 秒，參考影片總長度最多 15 秒。            |
| `reference_audios` | string\[] | 最多 5 個音訊 HTTP(S) URL。                                           |
| `file`             | string    | 公開的文件 URL。                                                      |
| `link`             | string    | 公開的網頁 URL。                                                      |
| `resolution`       | string    | 請見模型表格。預設值：`1080p`。                                             |
| `ratio`            | string    | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`。預設值：`adaptive`。 |
| `duration`         | integer   | 輸出長度為 2–30 秒，或使用 `-1` 自動決定長度。預設值：`5`。                           |
| `audio`            | boolean   | 生成音訊。預設值：`true`。停用音訊不會降低費率。                                     |
| `seed`             | integer   | 0–2147483647。省略時採隨機生成。                                          |
| `prompt_extend`    | boolean   | 擴充提示詞。預設值：`true`。                                               |

請使用穩定、可直接存取的媒體 URL，並確保任務完成前都能存取。影片時長檢查會透過 HTTP Range 請求讀取有限範圍的資料；影片伺服器必須支援這類讀取，並提供可讀取的 MP4/MOV 時長中繼資料。時長檢查不會跟隨重新導向，也不支援私人網路 URL。參考影片與輸出影片的合計長度不得超過 30 秒。Playground 接受的 JSON 請求主體上限為 32 MiB；較大的輸入請改用 URL。

## 輪詢並下載影片 [#輪詢並下載影片]

各款模型的提交端點都會回傳對外使用的任務 ID。請先儲存此 ID，再進行其他操作。

```json
{
  "task_info": {
    "id": "task_EXAMPLE",
    "status": "pending"
  }
}
```

請使用對應模型章節中的查詢範例。建議先以 5 秒為間隔查詢，遇到暫時性錯誤後再延長間隔。請一併儲存每個任務的模型 ID 與任務 ID，勿透過其他模型的端點查詢。

原生狀態為 `pending`、`processing`、`completed` 與 `failed`。完成後的回應包含 `videos` 陣列，其中提供完整的 Bunny CDN 簽名 URL。

```json
{
  "task_info": { "id": "task_EXAMPLE", "status": "completed" },
  "videos": ["https://reapiflexible.b-cdn.net/flexible/v1/expires/2026-11/20261113T06/wanapi-task_EXAMPLE/video.mp4?token=HS256_SIGNATURE&expires=1794550071"]
}
```

可直接使用回傳的 URL 播放或下載，存取該 URL 不需要 API 金鑰或 Authorization 標頭。檔案沿用儲存空間既有的保留政策。重新查詢任務不會重新生成影片、再次扣款或延長檔案保存期限。需要長期保存的檔案，請另存至自己的儲存空間。查詢任務仍須使用 API 金鑰，且只能取得自己帳號的任務。

## 同步與背景 Responses [#同步與背景-responses]

使用 Responses API 的用戶端，可透過 `POST /v1/responses` 傳入模型 ID、字串型別的 `input`，以及相同的原生生成欄位。請以 `input` 取代 `prompt`。`reference_images` 等原生媒體欄位仍放在頂層。

```json
{
  "model": "wan3.0-video",
  "input": "A blue ball rolls across a white table.",
  "resolution": "480p",
  "duration": 2,
  "background": true
}
```

設定 `background: true` 時，請儲存回應 ID，並輪詢 `GET /v1/responses/{response_id}`。未設定 `background` 時，HTTP 請求會等待生成完成。`stream: true` 會在等待期間使用伺服器發送事件（SSE）。最終助理輸出包含簽章影片 URL；持有此連結即可存取影片，請視為私密連結，避免意外公開。生成時間較長，或代理伺服器的逾時限制較嚴格時，建議使用原生任務提交或背景 Responses。

同步請求中斷或逾時不會取消生成，任務仍保留在伺服器上。請勿自動再次送出相同的生成請求。

## 計費與失敗處理 [#計費與失敗處理]

費用為模型對應解析度的費率乘以計費秒數。參考影片與輸出影片的秒數均計入；文字、圖片與音訊輸入不會增加影片計費秒數。未使用參考影片的固定長度請求，會依要求的輸出長度預留款項。自動長度或含參考影片的請求，會預留最多 30 個計費秒數的款項，再依實測用量結算並返還未使用的部分。生成失敗時會解除款項預留。輪詢不會建立另一個生成任務，也不會再次收費。

* \*\*參數無效：\*\*修正請求後再重新送出。不明的原生欄位會遭拒絕。
* \*\*餘額不足：\*\*請先儲值，再送出新的付費請求。金鑰的額度上限不代表帳號已有可用餘額。
* \*\*速率限制或暫時性輪詢失敗：\*\*僅重試查詢，逐步延長間隔，並設定最長等待時間。
* \*\*提交逾時、網路中斷或未取得任務 ID：\*\*提交結果可能不明。請勿自動重複 POST，否則可能建立第二個付費任務。
* \*\*任務失敗：\*\*請區分顯示任務失敗與無法查詢狀態。
* \*\*下載失敗：\*\*先重試下載已完成任務的結果，再考慮建立另一個生成任務。

生成請求不會自動重試，也不會自動切換至其他模型。目前未公布取消任務、webhook 或冪等鍵的介面規範。若提交結果不明而需要調查，請保留任務 ID 並聯絡[支援團隊](/zh-tw/contact)。