YUYU_M4 圖生圖

YUYU_M4 是圖片編輯模型:需要在 images 帶恰好 1 張欲編輯的來源圖,依 prompt 描述的指令修改這張圖(若帶多張,只會使用第一張;若沒有帶圖,建單當下仍會成功,但實際處理任務時會失敗並自動退款,比照〈YUYU_C1 圖生圖〉preset_name 送錯值的退款規則)。可用 width/height 控制輸出尺寸,is_enhanced 選填做二次強化。

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-00046" \
  -d '{
    "model": "YUYU_M4",
    "prompt": "turn the background into a beach at sunset",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "width": 1024,
    "height": 1024,
    "is_enhanced": false,
    "payload": { "external_order_id": "order-20260716-00046" },
    "callback_url": "https://example.com/webhooks/yuyu-image"
  }'

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

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY16",
  "type": 2,
  "status": 0,
  "credits": 10,
  "params": {
    "model": "YUYU_M4",
    "prompt": "turn the background into a beach at sunset",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "width": 1024,
    "height": 1024,
    "is_enhanced": false,
    "payload": { "external_order_id": "order-20260716-00046" },
    "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_M4
prompt	string	是	最長 10000 字
negative_prompt	string	否	負向提示詞,最長 500 字
images	string[]	否(強烈建議帶,否則任務會失敗並自動退款)	欲編輯的來源圖,建議恰好 1 張(若帶多張,只會使用第一張);完整 base64 data URI(data:image/{png|jpeg|webp};base64,...)
width / height	integer	否	最大 1024
is_enhanced	boolean	否	預設 false;設 true 時系統會用第一次產出的圖再跑一次 workflow(二次強化)
seed	integer	否	>= 0
resolution	—	否	不支援此參數,請改用 width/height,此欄位沒有效果,建議不要帶
payload	object	否	你自訂的透傳資料——原樣存入,查詢任務與〈回呼(Webhook)〉都會原封不動帶回,系統本身不解讀內容
callback_url	string	否	必須是 https:// 開頭的網址,最長 2000 字;見〈回呼(Webhook)〉

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

Idempotency-Key

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

Idempotency-Key: order-20260711-00046

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

回應

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

錯誤情境

狀態碼	情境	內容
422	參數驗證失敗(缺必填、型別錯、images 超過 4 張、width/height 超過 1024 等)	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
—	images 沒有帶欲編輯的來源圖	建單成功(201),但任務之後轉為失敗(status = 30)並自動退款,見上方說明

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