YUYU_M3 文字生圖

YUYU_M3 是純文字生圖模型:不需要 images,只靠 prompt 生成全新的圖片;width/height 選填,控制輸出尺寸(最大 1024)。

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

完整範例

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-00045" \
  -d '{
    "model": "YUYU_M3",
    "prompt": "beautiful woman, cinematic lighting",
    "negative_prompt": "blurry, watermark",
    "width": 1024,
    "height": 1024,
    "payload": { "external_order_id": "order-20260716-00045" },
    "callback_url": "https://example.com/webhooks/yuyu-image"
  }'

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

{
  "public_id": "01K1M2N3P4Q5R6S7T8V9W0XY15",
  "type": 2,
  "status": 0,
  "credits": 10,
  "params": {
    "model": "YUYU_M3",
    "prompt": "beautiful woman, cinematic lighting",
    "negative_prompt": "blurry, watermark",
    "width": 1024,
    "height": 1024,
    "payload": { "external_order_id": "order-20260716-00045" },
    "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_M3
prompt	string	是	最長 10000 字
negative_prompt	string	否	負向提示詞,最長 500 字
images	—	否	不需要,即使帶了也會被忽略
width / height	integer	否	最大 1024
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-00045

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

回應

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

錯誤情境

狀態碼	情境	內容
422	參數驗證失敗(缺必填、型別錯、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

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