萬相 Wan 影片 API 規範

本頁是阿里巴巴萬相影片模型 wan3.0-video、wan3.0-video-prime 的呼叫規範。這些模型與其他影片模型共用 POST /v1/videos 建立、GET /v1/videos/{id} 輪詢的流程；驗證、素材上傳、輪詢狀態、結果下載與錯誤處理請見影片 API 完整呼叫規範，本頁只列出萬相專屬的欄位與規則。萬相也可以用 POST /v1/responses 提交，見下文「用 Responses 介面呼叫」。

更新於 2026-10-12。原本的 wan3.0-video-480p、wan3.0-video-720p、wan3.0-video-1080p 已合併為 wan3.0-video，以 resolution 選擇解析度。首影格、尾影格和參考素材建議放在頂層 media 陣列（first_frame、last_frame、reference_image 等）；也支援 metadata.firstFrame、metadata.lastFrame、metadata.referenceImages、metadata.referenceVideos、metadata.referenceAudios（以及 metadata.first_frame 等底線寫法）和頂層 firstFrame／first_frame、lastFrame／last_frame，它們都會轉換為 media，但不能與 media 同時提交。無法識別的素材欄位會直接回傳 400。萬相只支援輪詢，請勿設定 callback_url。

模型一覽

模型	解析度	時長	比例	參考素材上限
`wan3.0-video`	480P / 720P / 1080P，預設 1080P	`-1` 或 2–30 秒，預設 5 秒	`adaptive` `16:9` `9:16` `1:1` `4:3` `3:4` `21:9`，預設 `adaptive`	圖 10／影片 5／音訊 5
`wan3.0-video-prime`	同上	同上	同上	同上

兩個模型能力一致：解析度、時長、比例、首尾影格與多素材參考的規則相同，請求參數通用，切換只需修改 model。差別在於生成速度：wan3.0-video-prime 是高速版，端到端生成明顯更快，適合需要盡快取得成片的情境；wan3.0-video 是標準版，對出片時間不敏感時選它即可。

通用規則

解析度：頂層 resolution 可為 480p、720p 或 1080p（不分大小寫），未傳時為 1080P。也可以用像素尺寸 size（例如 1280x720、1920x1080），會同時決定解析度與比例；size 也可以填寫比例（例如 "size": "9:16"），與 ratio／aspect_ratio 不一致時回傳 400。
時長：duration（或 seconds）填整數秒；-1 代表由模型智慧決定時長。
比例：使用 ratio（或等效的 aspect_ratio），兩者不一致時回傳 400。adaptive 代表依輸入素材自動調整。
提示詞：提供首影格或參考素材時可以省略 prompt，但建議寫明動作與鏡頭要求；兩者都沒有會回傳 400。
選填欄位：
- negative_prompt：負面提示詞；
- prompt_extend：是否自動改寫提示詞，布林值，預設為 true；
- watermark：是否加上浮水印，布林值；
- seed：整數，-1 到 2147483647。

{
  "model": "wan3.0-video",
  "prompt": "雨夜城市中的銀色跑車，低角度跟拍，霓虹倒影，電影感",
  "duration": 10,
  "resolution": "1080p",
  "ratio": "16:9"
}

首影格與首尾影格

首影格、尾影格請寫在 media 陣列中：first_frame 為首影格，last_frame 為尾影格（提供尾影格時必須同時提供首影格）。參考圖同樣放在 media（reference_image），規則見下一節。

{
  "model": "wan3.0-video-prime",
  "prompt": "從清晨空曠的廣場平順轉場到夜晚燈火亮起的同一構圖",
  "duration": 8,
  "resolution": "720p",
  "media": [
    { "type": "first_frame", "url": "https://cdn.example.com/start.jpg" },
    { "type": "last_frame", "url": "https://cdn.example.com/end.jpg" }
  ]
}

素材欄位的寫法

建議使用 media。也可以用頂層 images／image（第 1 張首影格、第 2 張尾影格）、metadata.firstFrame（或 metadata.first_frame）、頂層 firstFrame／first_frame 等寫法。無法識別的素材欄位（例如 metadata.image、metadata.images）會回傳 400 並提示改用 media；同一個素材用多種寫法提交且網址不一致時，也會回傳 400。

多素材參考：`media` 陣列

參考圖片、影片、音訊一律放在頂層 media 陣列，每一項為 { "type": "...", "url": "..." }：

`type`	用途	上限
`first_frame`	首影格	1
`last_frame`	尾影格，必須同時有 `first_frame`	1
`reference_image`	參考圖片	10
`reference_video`	參考影片	5
`reference_audio`	參考音訊	5

首影格／尾影格不能與參考圖片、影片、音訊混用。
提交 media 時只會讀取 media；images、image 等欄位中有 media 未包含的素材時回傳 400，首尾影格也請寫在 media 裡。
素材 URL 必須可匿名存取，要求請見素材 URL 要求；本機檔案請先依本機素材上傳取得 URL。萬相不接受 multipart/form-data 檔案上傳。

{
  "model": "wan3.0-video",
  "prompt": "參考圖中的人物隨參考音訊的節奏起舞，動作風格參考參考影片",
  "duration": 10,
  "resolution": "720p",
  "ratio": "9:16",
  "media": [
    { "type": "reference_image", "url": "https://cdn.example.com/dancer.jpg" },
    { "type": "reference_video", "url": "https://cdn.example.com/dance-motion.mp4" },
    { "type": "reference_audio", "url": "https://cdn.example.com/music.mp3" }
  ]
}

用 Responses 介面呼叫

這兩個模型也可以用 POST /v1/responses 提交，適合只能呼叫 Responses 介面的用戶端或工作流程。它和 /v1/videos 產生的是同一種影片任務，參數規則和計費完全相同。

提示詞寫在 input：可以是字串，也可以是訊息陣列。訊息裡的 input_text 作為提示詞，input_image 作為圖片素材，規則同頂層 images（第 1 張為首影格、第 2 張為尾影格）。
其他參數（resolution、duration、ratio、media、negative_prompt 等）照常寫在請求頂層，寫法與上文相同。
取得結果有三種方式：

方式	寫法	說明
同步等待	不傳 `stream` 和 `background`	連線保持到影片產生完成後直接回傳結果，最長等待約 10 分鐘。逾時會回傳 `"status": "incomplete"`，任務仍在繼續，用回傳的 `id` 查詢即可
背景提交	`"background": true`	立即回傳 `id`（狀態為 `queued` 或 `in_progress`），之後用 `GET /v1/responses/{id}` 輪詢，直到 `status` 為 `completed` 或 `failed`
串流	`"stream": true`	以 SSE 推送 `response.created`、`response.in_progress`（含進度），完成時推送 `response.output_text.done` 和 `response.completed`，失敗時推送 `response.failed`

{
  "model": "wan3.0-video-prime",
  "input": "雨夜城市中的銀色跑車，低機位跟拍，霓虹倒影，電影感",
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "background": true
}

產生完成後，影片網址在 output[0].content[0].text 中，格式為 <video controls src="影片網址"></video>，從 src 取出即可下載：

{
  "id": "resp_BVQwZLWyXB2dEU99F7nrER7XNJdVh8RS",
  "object": "response",
  "model": "wan3.0-video-prime",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "<video controls src=\"https://...\"></video>" }
      ]
    }
  ],
  "metadata": {
    "task_id": "task_BVQwZLWyXB2dEU99F7nrER7XNJdVh8RS",
    "task_status": "completed"
  }
}

metadata.task_id 是對應的影片任務號，也可以用 GET /v1/videos/{task_id} 查詢同一個任務。

對話介面不能產生影片

只有萬相支援 /v1/responses。/v1/chat/completions、/v1/messages 和生圖介面都不能呼叫影片模型，會回傳 400 video_model_wrong_endpoint。

計費

wan3.0-video 與 wan3.0-video-prime 是官方版，任務結果使用官方 URL。計費按官方規則：

計費時長 = 輸入影片時長 + 輸出影片時長

輸入影片時長：實際輸入的參考影片秒數；沒有參考影片時為 0。
輸出影片時長：成功產生的影片秒數。
單價依輸出解析度（480P / 720P / 1080P）計算，輸入影片與輸出影片使用同一檔單價。
參考圖片、參考音訊、文件和網頁不計入時長。
帶參考影片，或 duration 為 -1 時，提交按 30 秒預扣；完成後按模型平台回傳的輸入加輸出秒數結算，並退回差額。

具體每秒單價以模型廣場目前顯示為準。帶參考影片時不要只按輸出秒數估算費用。