建立圖片任務

POST /api/tasks/image-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/image-generation \
  -H "X-Api-Key: sk-live-xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260716-00043" \
  -d '{
    "model": "YUYU_C1",
    "prompt": "a woman smiling at the camera, studio lighting",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "preset_name": "some_preset",
    "quality": "high",
    "payload": { "external_order_id": "order-20260716-00043" },
    "callback_url": "https://example.com/webhooks/yuyu-image"
  }'

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

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY13",
  "type": 2,
  "status": 0,
  "credits": 10,
  "params": {
    "model": "YUYU_C1",
    "prompt": "a woman smiling at the camera, studio lighting",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "preset_name": "some_preset",
    "quality": "high",
    "payload": { "external_order_id": "order-20260716-00043" },
    "callback_url": "https://example.com/webhooks/yuyu-image"
  },
  "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_C1`(見下方說明)
`prompt`	string	依 `model` 而定	最長 10000 字(見下方)
`negative_prompt`	string	否	負向提示詞,最長 500 字
`images`	string[]	否	最多 4 張(圖生圖參考圖),元素為完整 base64 data URI(`data:image/{png\|jpeg\|webp};base64,...`)
`preset_name`	string	依 `model` 而定	見下方
`quality`	string	依 `model` 而定	見下方
`seed`	integer	否	`>= 0`
`resolution`	—	否	`YUYU_C1` 目前不支援調整解析度,此欄位對本模型沒有效果,建議不要帶
`payload`	object	否	你自訂的透傳資料——原樣存入,查詢任務與〈回呼(Webhook)〉都會原封不動帶回,系統本身不解讀內容
`callback_url`	string	否	必須是 `https://` 開頭的網址,最長 2000 字;見〈回呼(Webhook)〉

prompt/preset_name/quality 三欄依 model 而異:

`model`	`prompt`	`preset_name`	`quality`
`YUYU_C1`	選填	必填,字串(系統原生預設集名稱,見下方說明,合法性於實際處理任務時才會核實,送出不存在的值會導致建單失敗並自動退款)	必填,`low` / `mid` / `high`

`model` 值說明

model 對外值即模型代號：

YUYU_C1:YUYU VIDEO 提供的圖生圖模型。preset_name 直接沿用系統原生的預設集名稱,本平台不做枚舉驗證;quality 可選 low/mid/high。

`preset_name` 說明

preset_name 共 48 種可選值:anal_griping / bath_towel / bikini / blowjob_69 / blowjob_grand_slam / blowjob_pov / blowjob_sideview / bondage / breast_milk / bunny_suit / chain_leash / come_fuck_me / cum_on_body / cum_on_face / cunnilingus / custom / doggystyle_pov / doggystyle_sideview / fingering / handjob / jk_uniform / legsup / leopard_bikini / lingerie / masturbation / missionary_condoms / missionary_pov / missionary_sideview / remix_blowjob / remix_cowgirl / remix_doggystyle / remix_dress / remix_hold_dick / remix_kiss / remix_pronebone / remix_suck / remix_wear / remix_yoga / ride_on_dildo / sipping_condoms / squatting_cowgirl / tattoo / tentacles / titjob / topless / undress / used / xray。送出不存在的值,建單當下仍會成功(201),但系統實際處理此任務時會失敗,任務轉為失敗並自動退款(見〈積分與計費〉的退款規則),不是同步的 422 錯誤。

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

`Idempotency-Key`

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

Idempotency-Key: order-20260711-00043

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

回應

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

錯誤情境

狀態碼	情境	內容
`422`	參數驗證失敗(缺必填、型別錯、`images` 超過 4 張等)	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

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

建立圖片任務

完整範例

參數表

model 值說明

preset_name 說明

Idempotency-Key

回應

錯誤情境

`model` 值說明

`preset_name` 說明

`Idempotency-Key`