裝備變體
用途
將道具圖表中的道具裝備到角色基礎圖片上，並生成裝備後的變體。此功能與網頁應用程式「裝備變體」頁面相同。
代幣消耗： 5
方法與路徑
POST /public/v1/image-tune/equip-variation
認證
請參閱認證頁面。需要 Bearer Token。
必要標頭：
Authorization: Bearer {your_api_key}
請求欄位
請以 multipart/form-data 傳送請求。
| 欄位名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| character_image | file | 是 | 角色基礎圖片（PNG 或 JPEG） |
| item_sheet_image | file | 是 | 道具圖表圖片（PNG 或 JPEG） |
| prompt | string | 是 | 描述如何裝備道具的提示詞。會移除前後空白，且提示詞不得為空 |
回應
成功回應 (200 OK)：
{
"job_id": "uuid-string"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| job_id | string | 已建立作業的唯一識別碼。請使用取得作業狀態查詢結果 |
錯誤 / 驗證規則
| 情況 | HTTP 狀態 | 錯誤訊息 |
|---|---|---|
| 任一圖片不是有效的 PNG 或 JPEG 檔案 | 400 | "Invalid image file" |
| prompt 為空 | 400 | "prompt must not be empty" |
| 無效的 API 金鑰 | 401 | "Invalid API key" |
| 欄位遺漏 | 422 | Validation error |
兩張圖片都會在上傳任何內容之前完成驗證，因此失敗的請求不會留下部分上傳的檔案。
非同步作業行為
此端點會建立非同步作業。它會立即回傳 job_id，生成會在背景進行。
輪詢方法：
- 儲存回應中收到的
job_id - 輪詢
GET /public/v1/job/{job_id}確認狀態 - 當狀態變為
Succeed時，於image_urls查看結果
狀態流程： Pending → Succeed 或 Failed
請求範例
cURL：
curl -X POST "https://api.aetherforgeai.com/public/v1/image-tune/equip-variation" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "character_image=@/path/to/character.png" \
-F "item_sheet_image=@/path/to/item_sheet.png" \
-F "prompt=equip the iron sword and the leather helmet"