Sprite Plus
用途
根據起始幀與可選的結束幀生成精靈動畫。此功能與網頁應用程式「生成精靈」頁面（Sprite Lite & Plus）的 Plus 分頁相同。使用 frame 選擇幀數，與網頁頁面滑桿上顯示的值完全相同。
代幣消耗： 9（49 幀）、13（81 幀）
方法與路徑
POST /public/v1/sprite/plus
認證
請參閱認證頁面。需要 Bearer Token。
必要標頭：
Authorization: Bearer {your_api_key}
請求欄位
請以 multipart/form-data 傳送請求。
| 欄位名稱 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
| start_image | file | 是 | 起始幀（PNG 或 JPEG） | |
| end_image | file | 否 | 結束幀（可選）（PNG 或 JPEG） | |
| text | string | 是 | 描述動作的提示詞。會移除前後空白，且文字不得為空 | |
| frame | integer | 是 | 幀數。允許的值：49、81 | |
| is_pixel | boolean | 否 | false | 像素風。如果附加圖片本身是像素風，請開啟此選項 |
| is_prompt_enhancement | boolean | 否 | true | 提示詞優化。根據你輸入的內容，將提示詞優化為更適合生成精靈的形式 |
依 frame 的代幣
| frame | 代幣 |
|---|---|
| 49 | 9 |
| 81 | 13 |
回應
成功回應 (200 OK)：
{
"job_id": "uuid-string"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| job_id | string | 已建立作業的唯一識別碼。請使用取得作業狀態查詢結果 |
錯誤 / 驗證規則
| 情況 | HTTP 狀態 | 錯誤訊息 |
|---|---|---|
| 任一圖片不是有效的 PNG 或 JPEG 檔案 | 400 | "Invalid image file" |
| frame 值不允許 | 400 | "frame should be one of 49, 81" |
| text 為空 | 400 | "text 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查看結果（精靈圖表與 GIF）
狀態流程： Pending → Succeed 或 Failed
請求範例
cURL (僅起始幀)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/plus" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "start_image=@/path/to/character.png" \
-F "text=walking animation" \
-F "frame=49" \
-F "is_pixel=true"
cURL (起始幀 + 結束幀)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/plus" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "start_image=@/path/to/character_start.png" \
-F "end_image=@/path/to/character_end.png" \
-F "text=running animation cycle" \
-F "frame=81"