YUYU_N1 圖生影片

YUYU_N1 是 YUYU VIDEO 提供的圖生影片模型:duration 可調 2–15 秒、audio 可調有聲/靜音、resolution 可選 720p/1080p,適合需要依素材調整輸出規格的場景。

POST /api/tasks/video-generation
X-Api-Key: sk-live-xxxx
Content-Type: application/json
Idempotency-Key: 選填,見下方說明

完整範例

images 只接受完整的 base64 data URI(png/jpeg/webp 三種 MIME 皆可),這裡為了範例簡短省略實際 base64 內容:

curl -X POST https://example.com/api/tasks/video-generation \
  -H "X-Api-Key: sk-live-xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260716-00042" \
  -d '{
    "model": "YUYU_N1",
    "prompt": "a woman waving at the camera, cinematic lighting",
    "negative_prompt": "blurry, low quality",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "duration": 5,
    "resolution": "720p",
    "audio": true,
    "seed": 1234567,
    "payload": { "external_order_id": "order-20260716-00042" },
    "callback_url": "https://example.com/webhooks/yuyu-video"
  }'

成功回 201 Created(任務剛建立時是待派工狀態,result/files 尚無內容）：

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY12",
  "type": 1,
  "status": 0,
  "credits": 20,
  "params": {
    "model": "YUYU_N1",
    "prompt": "a woman waving at the camera, cinematic lighting",
    "negative_prompt": "blurry, low quality",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "duration": 5,
    "resolution": "720p",
    "audio": true,
    "seed": 1234567,
    "payload": { "external_order_id": "order-20260716-00042" },
    "callback_url": "https://example.com/webhooks/yuyu-video"
  },
  "error_code": null,
  "error_message": null,
  "created_at": "2026-07-16T08:00:00.000000Z",
  "finished_at": null,
  "files_expire_at": null,
  "files_expired": false,
  "files": []
}

之後如何查詢這筆任務的進度、任務完成後怎麼取得影片,見〈任務查詢與取件〉。

參數表

欄位	型別	必填	規則
model	string	是	固定為 YUYU_N1
prompt	string	是	最長 10000 字
negative_prompt	string	否	負向提示詞,最長 500 字
images	string[]	是	恰好 1 張(size:1);完整 base64 data URI(data:image/{png|jpeg|webp};base64,...)
duration	integer	否	2–15,預設 5
audio	boolean	否	是否輸出有聲影片,預設 true
resolution	string	否	720p / 1080p,預設 720p
seed	integer	否	>= 0
payload	object	否	你自訂的透傳資料——原樣存入,查詢任務與〈回呼(Webhook)〉都會原封不動帶回,系統本身不解讀內容
callback_url	string	否	必須是 https:// 開頭的網址,最長 2000 字;見〈回呼(Webhook)〉

帶入未知的 model 值會收到 422:Unknown model alias: {model}。

Idempotency-Key

在 header 帶上任意字串(建議用你系統內該次請求的唯一識別碼,如訂單編號):

Idempotency-Key: order-20260711-00042

同一組 API Key + 同一個 Idempotency-Key 值,短時間內重複送出同一請求,只會建立一筆任務;之後的重複請求會回傳同一筆既有任務(不會重新扣款、不會建立第二筆任務)。適合用在你的系統有重試機制、又不希望重試造成重複扣款的場景。不帶這個 header 則每次請求都會建立新任務。

回應

成功建立回 201 Created(冪等命中既有任務則回 200 OK),內容是〈任務查詢與取件〉描述的任務物件。

錯誤情境

狀態碼	情境	內容
422	參數驗證失敗(缺必填、型別錯、images 不是恰好 1 張、duration/resolution/audio 不在允許範圍等)	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

實際會扣多少積分、建立後如何查詢進度與取得結果,見〈任務查詢與取件〉與〈積分與計費〉。