全能參考影片
POST /api/tasks/reference2video
X-Api-Key: sk-live-xxxx
Content-Type: application/json
Idempotency-Key: 選填,見下方說明
全能參考影片是以參考圖為素材、依 prompt 生成全新畫面的影片任務。跟〈圖生影片〉最大的不同是 images 的意思:
| 〈圖生影片〉 | 全能參考影片(本頁) | |
|---|---|---|
| 端點 | POST /api/tasks/video-generation |
POST /api/tasks/reference2video |
images 的角色 |
首幀圖:影片從這張圖開始動起來 | 參考圖:提供角色/場景/物件的外觀,畫面依 prompt 重新構圖,不一定從參考圖開始 |
| 參考圖張數 | 恰好 1 張 | 依模型而定,YUYU_N1 最多 5 張(選填),YUYU_M6 恰好 1 張 |
| 畫面比例 | 跟隨輸入圖 | 依模型而定,YUYU_N1 可用 aspect_ratio 指定,YUYU_M6 跟隨參考圖 |
任務類型(type) |
1 |
4 |
兩個端點是各自獨立的任務類型:同一個 model 在兩邊的參數規格、可用範圍與計價都可能不同(例如 YUYU_N1 在圖生影片可調 2–15 秒,在全能參考影片是 2–10 秒),請以各模型頁面為準。各模型的扣點由平台設定,實際扣點以建單回應的 credits 欄位為準,見〈積分與計費〉。
支援的模型
| Model | 參考圖 | 時長 | 解析度/比例 | 音訊 |
|---|---|---|---|---|
| YUYU_N1 | 選填,最多 5 張,依陣列順序對應角色 | 2–10 秒(預設 5) |
720p/1080p;aspect_ratio 五種比例可選 |
可選有聲/靜音(預設有聲) |
| YUYU_M6 | 恰好 1 張 | 固定 5 秒(必填) |
不可調,畫面比例跟隨參考圖 | 不可調 |
- 不知道選哪個? 要放多個角色、指定畫面比例或解析度 →
YUYU_N1。只有一張參考圖、要固定 5 秒的短片 →YUYU_M6。
每個模型的完整參數表、curl 範例、回應範例與錯誤情境請見對應頁面(彼此互相獨立,任何一頁都可以單獨閱讀):
共用參數
以下欄位兩個模型都適用;各模型特有的欄位(duration、resolution、aspect_ratio、audio、seed 等)見各模型頁面。
| 欄位 | 型別 | 必填 | 規則 |
|---|---|---|---|
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)〉 |
帶入未知的 model 值會收到 422:Unknown model alias: {model}。
Idempotency-Key
在 header 帶上任意字串(建議用你系統內該次請求的唯一識別碼,如訂單編號):
Idempotency-Key: order-20261001-00042
同一組 API Key + 同一個 Idempotency-Key 值,短時間內重複送出同一請求,只會建立一筆任務;之後的重複請求會回傳同一筆既有任務(不會重新扣款、不會建立第二筆任務)。不帶這個 header 則每次請求都會建立新任務。
回應與取件
成功建立回 201 Created(冪等命中既有任務則回 200 OK),內容是〈任務查詢與取件〉描述的任務物件,type 為 4。任務完成後 result 的鍵是 video,跟圖生影片一樣從 files[].url 下載;也可以帶 callback_url 改用〈回呼(Webhook)〉接收完成通知。
錯誤情境
| 狀態碼 | 情境 | 內容 |
|---|---|---|
422 |
參數驗證失敗(缺必填、型別錯、images 張數不符該模型、duration 等不在該模型允許範圍) |
Laravel 標準 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 |
完整錯誤碼對照見〈錯誤總表〉。