API 參考
圖片：非同步任務
POST
/v1/images/tasksGET
/v1/images/tasks/{task_id}GET
/v1/images/tasks/{task_id}/content非同步圖片生成，目錄裡的圖片模型都走這個路由。提交後回傳 task_id；輪詢狀態端點，再從 /content 讀取長期有效的結果 URL；也可以註冊 webhook，省去輪詢。
#請求參數
modelstring必填非同步圖片模型 ID，如 gpt-image-2。同步模型會拒絕該端點。
promptstring必填要畫什麼。
sizestring選填長寬比，如 "16:9"，大多數圖片模型都用這種寫法，可選值見模型卡。部分舊模型也接受像素寫法 WIDTHxHEIGHT。
resolutionstring選填輸出解析度檔位，如 "1K"、"2K"、"4K"，模型卡裡有這個參數時才能用；也影響計費檔位。
qualitystring選填廠商品質等級（如 standard / hd）——同樣是計費檔位維度。
ninteger選填生成張數（按張數疊加計費）。
imagesarray選填要修改或參照的圖片，填網址或 data URI。每個模型最多收幾張，以模型卡為準。
maskstring選填只重畫第一張參考圖上的一塊區域，見下方「只改圖片的一部分」。模型卡裡列出 mask 的模型才收這個欄位；寫成 mask_url 也一樣。
webhook_urlstring選填任務到達終態時回呼的 HTTPS 網址——回呼契約見影片指南。
webhook_secretstring選填設定後，回呼帶 X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret))。
每個模型的參數不一樣
每個模型能填哪些欄位、取哪些值，以模型卡為準。gpt-image-2.5-ext 的 size 填長寬比，再配 resolution；像 2560x1088 這樣的像素尺寸會換成最接近的長寬比和解析度（21:9、2K）。它不能設定 background："auto" 會被忽略，其他值會被拒絕。每次只出一張圖，也不能選 version：不傳，或者傳 "flare"。
欄位名稱可能因模型家族而異
任務狀態負載來自上游廠商的原樣回報；具體欄位以實際回應為準，可依賴的是跨廠商穩定的 task_id、status 和 /content 端點。
#只改圖片的一部分
在 images 裡放原圖，再傳一個 mask：只重畫遮罩圈出的區域，其他地方保持不變。在 prompt 裡寫清那塊要變成什麼。目前 gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 支援；模型卡上顯示為 mask 欄位。
curl https://www.aisplice.store/v1/images/tasks \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-flare",
"prompt": "Replace the mug with a glass of orange juice; keep everything else",
"images": ["https://example.com/desk.png"],
"mask": "https://example.com/desk-mask.png",
"resolution": "1K"
}'遮罩怎麼做
用帶透明通道的 PNG：完全透明的像素就是要重畫的地方，其餘保留。尺寸必須和第一張參考圖的像素尺寸完全一樣（不是輸出尺寸），不超過 4 MB。每次只能傳一張遮罩；有多張參考圖時，只作用在第一張上。用 gpt-image-2.5 模型時不要傳 size，結果會保持原圖的比例。
- 400 invalid_request傳了 mask 但沒有參考圖，或者這個模型不收 mask（gpt-image-2.5-ext 會回傳 "mask is not supported on Ext"）。
#相關錯誤碼
- 404 not_found路徑不存在、模型名稱不存在，或 task_id 已過期 / 不屬於目前帳號。
- 401Bearer 權杖無效或缺失。這條路徑不帶 error.code，請依狀態碼判斷。
- 402 insufficient_user_quota錢包餘額不足以覆蓋預扣估算。
- 429金鑰級限流。回應主體為空，按 Retry-After 等待。若 429 帶有 insufficient_user_quota，那是每日消費上限，不是限流。
- 503 model_not_found模型名稱不存在，或目前沒有健康的通道可以提供服務。
#請求範例
# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'
# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"
# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"#回應
response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}
// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}
// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}還是沒解決？
把請求 ID 或錯誤訊息傳給我們，我們來查。