Wan 3.0 Video Prime API

透過 APIMaster 非同步影片 API 使用 wan3.0-video-prime。目前的整合提供 480P / 720P / 1080P、2–30 整數秒，且每個任務一個影片。參數與整合審查：2026-10-26。

端點與驗證

操作	方法與 URL
建立	POST https://apimaster.ai/v1/videos
查詢	GET https://apimaster.ai/v1/videos/{task_id}
下載	GET https://apimaster.ai/v1/videos/{task_id}/content

在每個請求上使用 Authorization: Bearer YOUR_API_KEY，建立任務時使用 Content-Type: application/json。請使用 APIMaster API 金鑰，而非阿里雲金鑰。APIMaster 會提供上游非同步標頭；您不需要 X-DashScope-Async。

相容的建立端點 /videos/generations 會傳回不同的回應封裝；以下範例一律使用 /videos。

目前路由能力

目前有兩種整合服務此模型：阿里雲原生路由與 GMI 路由。進階欄位需要對應的路由；提交欄位並不會選擇該路由。使用路由特定範例前，請先確認您的 API 金鑰可存取哪個路由。

能力	阿里雲原生	GMI
文字轉影片、第一幀、第一/最後幀、參考圖片	已整合	已整合，但媒體欄位不同
參考音訊	metadata.input.media	audio_url
文件 / 公開網頁	原生媒體欄位會被轉送；不在已完成的生成檢查涵蓋範圍內	不支援
參考影片、編輯、延長	提交前即封鎖	不支援
自動時長 -1	封鎖	封鎖
長寬比 21:9	接受	拒絕
明確音訊開關	generate_audio / audio	不支援；請省略這些欄位
停用提示改寫 / 固定種子 0	目前的序列化不會保留 prompt_extend: false 或 seed: 0；請勿依賴它們	明確的 false 與 0 會被保留

原生路由的 5 秒 720P 無聲影片在 2026-10-24 的驗收檢查中成功完成、下載並解碼。其他媒體組合是根據轉接器與官方合約描述，而非以經過生成測試的組合呈現。路由可用性與價格可能變動；請參閱模型卡。

完整通用請求參數

請在頂層傳送這些欄位。為獲得最廣泛的相容性，請使用明確的 duration、resolution 與 aspect_ratio，非空且最多 5,000 字元的提示，並省略路由特定選項。

欄位	類型	必填 / 預設	APIMaster 行為
model	string	必填	必須為 wan3.0-video-prime
prompt	string	兩個路由皆必填	非空，包含圖片生成。GMI 驗證 1–5,000 字元；原生轉接器要求非空文字。官方原生上限為 20,000；避免跨路由依賴該較高上限
duration	integer	5	2–30 秒；不可為 -1、小數或自動時長
seconds	string	選填	字串別名，例如 "5"；兩者皆提供時必須與 duration 一致
resolution	string	720P	480P、720P、1080P；頂層小寫值會被正規化。此 APIMaster 預設值與官方原生預設值不同
aspect_ratio	string	16:9	常用值：adaptive、16:9、9:16、1:1、4:3、3:4。21:9 僅限原生路由
ratio	string	選填	aspect_ratio 的別名；請使用其中一個欄位，且不要傳送衝突的值
size	string	選填	尺寸別名，例如 1280x720；適用路由特定驗證。建議優先使用 resolution 與 aspect_ratio。GMI 要求較短邊符合解析度等級；原生僅接受其支援的尺寸對應
input_reference	string	選填	第一幀圖片 URL。為跨路由相容性，請使用可公開下載的 HTTP(S) URL；請勿與其他第一幀輸入合併使用
prompt_extend	boolean	原生 true；GMI 省略時保留供應商預設值	提示改寫。原生目前無法可靠地以 false 停用它；GMI 會轉送明確的布林值
watermark	boolean	官方原生預設 false；GMI 省略時保留供應商預設值	浮水印開關
seed	integer	省略時隨機	可攜的固定範圍：1–2147483647。原生也接受 -1 表示隨機；原生 0 會在序列化時被省略。GMI 接受 0–2147483647 並拒絕 -1。固定種子不保證輸出完全相同

原生尺寸別名為 832x480、480x832、1280x720、720x1280、1920x1080 與 1080x1920，適用於常見的橫向/縱向情況。部分正方形尺寸對應會化簡為 1:1；其他對應尺寸仍可能無法通過長寬比驗證。請勿使用 size 請求任意尺寸。

路由特定參數表

GMI 欄位

這些是通用表之外的頂層欄位。GMI 轉接器會拒絕無法辨識的欄位，包括 metadata、images、image_urls、audio、generate_audio、video_urls 與 reference_video。

欄位	類型	必填 / 預設	行為
negative_prompt	string	選填	最多 500 字元
first_frame	string	選填	公開 HTTP(S) 圖片 URL；input_reference 的替代方案
last_frame	string	選填	公開 HTTP(S) 最後幀圖片 URL；也需提供第一幀
reference_image	string 或 string[]	選填	1–10 個公開 HTTP(S) 參考圖片 URL；多張圖片請使用陣列
audio_url	string	選填	公開 HTTP(S) 參考音訊 URL；受供應商媒體驗證約束

在單一請求中請使用幀控制或參考圖片兩者之一。原生的 metadata.input.media 在 GMI 上不會被轉譯為這些欄位。

阿里雲原生欄位

原生結構化輸入屬於 metadata 之內。直接在頂層傳送官方 input 或 parameters 物件並非 APIMaster 合約。請務必保留必填的頂層 prompt。

欄位	類型	必填 / 預設	行為
generate_audio	boolean	官方原生預設 true	輸出是否包含音軌；false 會被保留
audio	boolean	選填	generate_audio 的別名；僅提供其中一個
images	string[]	選填	會轉換為 reference_image 媒體項目；這些不是有序的第一/最後幀。請勿與 input_reference 合併使用
metadata	object	選填	包裝原生 input 與 parameters；無法變更 model
metadata.input	object	選填	原生輸入容器
metadata.input.prompt	string	選填	原生提示覆寫；建議只使用頂層提示
metadata.input.media	object[]	選填	原生媒體集合，每個項目均含 type 與 url
metadata.input.media[].type	string	每個項目必填	first_frame、last_frame、reference_image、reference_audio、file、link；reference_video 目前會被拒絕
metadata.input.media[].url	string	每個項目必填	媒體位置；建議使用公開 HTTP(S) URL。官方 OSS 臨時 URL 需要另行有效的上游上傳情境；APIMaster 不提供該上傳情境
metadata.parameters	object	選填	原生參數容器；不得為 null
metadata.parameters.resolution	string	720P	大寫 480P、720P、1080P
metadata.parameters.ratio	string	16:9	原生長寬比，包含 adaptive 與 21:9
metadata.parameters.duration	integer	5	2–30；不可為 -1
metadata.parameters.audio	boolean	官方原生預設 true	輸出音訊開關
metadata.parameters.prompt_extend	boolean	true	對 file / link 必須保持 true；明確的 false 有上述序列化限制
metadata.parameters.watermark	boolean	官方原生預設 false	浮水印開關
metadata.parameters.seed	integer	隨機	-1 或 0–2147483647；0 有上述序列化限制

頂層原生選項會覆寫其對應的中繼資料參數。頂層 input_reference 會取代原生媒體陣列；當 input_reference 不存在時，images 會附加參考圖片項目。請使用單一輸入風格與單一參數風格，以避免意外覆寫。請勿在原生 input 中使用舊版 img_url、first_frame_url、last_frame_url 或 audio_url；轉接器會拒絕 Wan 3.0 的這些舊版媒體欄位。

媒體限制

以下官方原生媒體規則也說明了供應商端驗證；轉接器接受 URL 並不代表媒體有效。

媒體	限制 / 整合備註
第一 / 最後幀	各最多一個；最後幀需要第一幀。請勿將幀控制與 reference_image 混用
參考圖片	最多 10 張；JPEG/JPG、不含透明度的 PNG、BMP 或 WEBP；每邊 240–8,000 px，長寬比最多 8:1，每張最多 20 MB
參考音訊	原生：最多 5 個，WAV/MP3，每個 1–15 秒，合計最多 15 秒，每個檔案最多 15 MB。GMI 提供一個 audio_url
檔案 / 網頁	僅限原生：最多一個檔案或一個可公開讀取的頁面；請勿合併 file 與 link。官方檔案格式：DOCX、DOC、XLSX、XLS、PPTX、PPT、PDF、TXT、KEY、PAGES、NUMBERS、MD；最多 100 MB，適用分頁格式時上限 50 頁。請保持 prompt_extend: true
參考影片	官方提供，但目前被 APIMaster 原生計費驗證封鎖；GMI 未暴露。請勿在此使用官方 API 的影片編輯或延長範例

官方原生合併媒體上限為 20 個項目；個別與組合限制仍然適用。圖片 Base64 資料 URL 屬於官方原生輸入格式的一部分，但不被 GMI URL 驗證接受。跨路由請優先使用可下載的 HTTP(S) URL。

範例

文字轉影片，通用欄位

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'

第一幀，通用欄位

{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}

GMI 第一 / 最後幀

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}

原生第一 / 最後幀與無聲輸出

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}

原生參考圖片與音訊

{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood of audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}

請將範例媒體 URL 替換為真實的公開檔案。路由特定範例需要對應的路由，且仍受上游組合檢查約束。

回應、輪詢與下載

建立會傳回 APIMaster 任務 ID，例如：

{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}

欄位	意義
id / task_id	APIMaster 任務識別碼，而非上游任務識別碼
status	queued、in_progress、completed、failed
progress	回報的進度；不保證完成
error.code / error.message	適用時的失敗詳細資料
metadata.url	完成時傳回經驗證的內容位址

使用相同的 API 金鑰每 10–20 秒輪詢一次，直到終止狀態；建立成功僅表示已受理。生成可能需要數分鐘。請輪詢已受理的任務，而不要重複建立付費任務。

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o wan-prime.mp4

請及時下載並儲存完成的影片；上游結果 URL 可能過期。重複輪詢不會產生另一次生成費用。

計費與常見錯誤

計費依請求解析度按秒計算，路由/帳戶定價顯示於模型卡。提交時會預留預估費用。原生完成時使用傳回的計費時長與凍結的提交價格；GMI 遵循預留時長合約。失敗的任務會釋放/退還其生成預留。關閉音訊不代表較便宜的等級。最終金額請使用用量記錄。

錯誤 / 症狀	動作
duration must be an integer from 2 to 30	使用明確整數；-1 未整合
unsupported Wan request field ...	移除 GMI 不支援的欄位，或確認可存取對應的原生路由
unsupported aspect ratio	使用常用比例；21:9 需要原生路由
reference video requires an input-duration quote	移除參考影片；此能力目前被封鎖
prompt is required / 媒體擷取失敗	新增頂層文字；使用可公開下載的有效媒體
prompt_extend: false 或 seed: 0 在原生上無效	目前的序列化限制；使用正數種子，且不要依賴停用改寫

來源：官方模型資訊、官方原生 API 參考 與 官方使用指南。官方能力並不代表相同欄位會在每個 APIMaster 路由上暴露。