YUYU_N1 全能參考影片

YUYU_N1 在全能參考影片可以帶最多 5 張參考圖(角色、場景、物件都可以),依 prompt 生成全新的畫面:duration 可調 2–10 秒、resolution 可選 720p/1080p、aspect_ratio 可指定畫面比例、audio 可調有聲/靜音,適合多角色同框或需要指定橫/直式畫面的場景。

這是〈全能參考影片〉端點的 YUYU_N1,規格跟〈YUYU_N1 圖生影片〉不同(例如時長上限是 10 秒,不是 15 秒),請勿混用兩頁的參數表。

POST /api/tasks/reference2video
X-Api-Key: sk-live-xxxx
Content-Type: application/json
Idempotency-Key: 選填,見〈全能參考影片〉的說明

完整範例

images 只接受完整的 base64 data URI(png/jpeg/webp 三種 MIME 皆可),這裡為了範例簡短省略實際 base64 內容。陣列順序就是角色順序:第 1 張是第一個角色、第 2 張是第二個角色,prompt 裡可以用這個順序描述誰做什麼:

curl -X POST https://example.com/api/tasks/reference2video \
  -H "X-Api-Key: sk-live-xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261001-00042" \
  -d '{
    "model": "YUYU_N1",
    "prompt": "the woman from image 1 and the man from image 2 walk side by side on a beach at sunset, cinematic lighting",
    "images": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "audio": true,
    "payload": { "external_order_id": "order-20261001-00042" },
    "callback_url": "https://example.com/webhooks/yuyu-video"
  }'

成功回 201 Created(任務剛建立時是待派工狀態,result/files 尚無內容;params 會補上你沒帶的欄位預設值;credits 是這次實際扣款的積分,下方範例的數字僅為示意,實際以平台設定為準):

{
  "public_id": "01K6A1B2C3D4E5F6G7H8J9K0LM",
  "type": 4,
  "status": 0,
  "credits": 20,
  "params": {
    "model": "YUYU_N1",
    "prompt": "the woman from image 1 and the man from image 2 walk side by side on a beach at sunset, cinematic lighting",
    "images": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "audio": true,
    "payload": { "external_order_id": "order-20261001-00042" },
    "callback_url": "https://example.com/webhooks/yuyu-video"
  },
  "error_code": null,
  "error_message": null,
  "created_at": "2026-10-01T08:00:00.000000Z",
  "finished_at": null,
  "files_expire_at": null,
  "files_expired": false,
  "files": []
}

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

參數表

欄位	型別	必填	規則
model	string	是	固定為 YUYU_N1
prompt	string	是	最長 1500 字
images	string[]	否	0–5 張參考圖,依陣列順序對應角色;完整 base64 data URI(data:image/{png|jpeg|webp};base64,...)
duration	integer	否	2–10,預設 5
resolution	string	否	720p / 1080p,預設 720p
aspect_ratio	string	否	16:9 / 9:16 / 1:1 / 3:4 / 4:3,預設 16:9
audio	boolean	否	是否輸出有聲影片,預設 true
payload	object	否	你自訂的透傳資料——原樣存入,查詢任務與〈回呼(Webhook)〉都會原封不動帶回,系統本身不解讀內容
callback_url	string	否	必須是 https:// 開頭的網址,最長 2000 字;見〈回呼(Webhook)〉

• 這個端點的 YUYU_N1 不支援 seed(送了會被忽略,不會出現在 params 裡),也不採用 negative_prompt;想避免的內容請直接寫進 prompt。

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

回應

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

錯誤情境

狀態碼	情境	內容
422	參數驗證失敗(缺必填、型別錯、images 超過 5 張、prompt 超過 1500 字、duration/resolution/aspect_ratio/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

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