全能參考影片
POST /api/tasks/reference2video
X-Api-Key: sk-live-xxxx
Content-Type: application/json
Idempotency-Key: 選填,見下方說明
全能參考影片會參考你提供的圖片(角色、場景或物件的外觀),再依照 prompt 生成全新的畫面。
和〈圖生影片〉的差別:
| 圖生影片 | 全能參考影片 | |
|---|---|---|
| API | POST /api/tasks/video-generation |
POST /api/tasks/reference2video |
| 圖片的用途 | 當作影片的第一個畫面,影片從這張圖開始動 | 參考角色、場景或物件的外觀,畫面依 prompt 重新安排,不一定從這張圖開始 |
| 圖片張數 | 1 張 | 依模型不同:YUYU_N1 最多 5 張(也可以不放),YUYU_M6 1 張 |
| 畫面比例 | 跟著圖片 | 依模型不同:YUYU_N1 可用 aspect_ratio 指定,YUYU_M6 跟著參考圖 |
任務類型(type) |
1 |
4 |
同一個模型在兩個 API 的規格和價格可能不同。例如 YUYU_N1 在圖生影片可選 2–15 秒,在全能參考影片是 3–10 秒,請以各模型頁面為準。
實際扣除的積分以回應中的 credits 為準。影片以每 5 秒為一個計費單位,不足 5 秒以 5 秒計,詳見〈積分與計費〉。
支援的模型
| 模型 | 參考圖 | 影片長度 | 解析度與比例 | 聲音 |
|---|---|---|---|---|
| YUYU_N1 | 可不放,最多 5 張,依順序對應角色 | 3–10 秒(預設 5 秒) | 目前只有 540p;可選 5 種畫面比例 |
有聲或靜音(預設有聲) |
| YUYU_M6 | 1 張 | 固定 5 秒 | 不可調整,畫面比例跟著參考圖 | 不可調整 |
怎麼選:
- 需要多個角色同框,或要指定畫面比例:選
YUYU_N1 - 只有一張參考圖,做固定 5 秒的短片:選
YUYU_M6,可另外開啟提示詞優化
共用參數
以下欄位兩個模型都適用。各模型專屬的欄位(例如 duration、aspect_ratio、audio)請看各模型頁面。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
model |
string | 是 | YUYU_N1 或 YUYU_M6 |
prompt |
string | 是 | 描述想要的畫面和動作。字數上限依模型不同:YUYU_N1 1500 字、YUYU_M6 10000 字 |
images |
string[] | 依模型 | 參考圖,格式為 base64 data URI(data:image/{png|jpeg|webp};base64,...),張數依模型不同 |
payload |
object | 否 | 自訂資料,例如你的訂單編號。系統不會讀取或修改,查詢任務和 Webhook 通知時會原樣帶回 |
callback_url |
string | 否 | 任務結束時要通知的網址,需以 https:// 開頭,最多 2000 字。詳見〈回呼(Webhook)〉 |
age_declared |
boolean | 否 | 有放參考圖時,系統會先偵測人物年齡。帶 true 表示你確認圖中人物都已成年,詳見〈生成前年齡檢查〉 |
model 填了不存在的模型會回傳 422:Unknown model alias: {model}。各模型頁沒有列出的參數帶了會回傳 422,不會被忽略。
Idempotency-Key
用來避免重複建立任務。在 header 帶上一組自訂字串,建議用你系統裡的訂單編號這類不會重複的值:
Idempotency-Key: order-20261001-00042
用同一把 API 金鑰、同一個 Idempotency-Key,在短時間內重複送出請求,只會建立一筆任務,也只扣一次積分。之後的重複請求會回傳 200 OK 和原本那筆任務。
不帶這個 header 的話,每次請求都會建立新任務。
回應與下載
建立成功會回傳 201 Created 和任務資料,type 為 4。資料格式請見〈任務查詢與取件〉。
任務完成後,result 裡的影片欄位名稱是 video,下載方式和圖生影片一樣,使用 files 裡的 url。也可以帶 callback_url,改用〈回呼(Webhook)〉接收完成通知。
錯誤情境
| 狀態碼 | 原因 | 回應內容 |
|---|---|---|
422 |
參數有誤,例如缺少必填欄位、型別錯誤、images 張數不符合模型規定、duration 等欄位超出模型允許範圍 |
errors 欄位會列出每個欄位的錯誤原因 |
422 |
model 填了不存在的模型 |
{ "message": "Unknown model alias: {model}" } |
402 |
積分不足 | { "message": "Insufficient credits to complete this charge." } |
429 |
排隊中的全能參考影片任務太多 | { "message": "Too many pending tasks of this type; please retry later." }。可以依回應的 Retry-After header 決定多久後再試 |
所有錯誤代碼請見〈錯誤總表〉。