Sprite Zenith
用途
使用 Zenith 流程生成精靈動畫。此功能與網頁應用程式「Sprite Zenith」頁面相同，並支援其三種模式：
| mode | 網頁分頁 | 輸入 |
|---|---|---|
image_to_video | 單張圖片 | 一張圖片 |
first_last_frame | 開始/結束參考圖片 | 兩張圖片：依序為起始幀與結束參考圖片 |
video_restyle | Sprite To Sprite | 一 個現有精靈（PNG 精靈圖表 + 網格，或 GIF）以及可選的參考圖片 |
代幣消耗： 9（36 幀）、25（100 幀）
方法與路徑
POST /public/v1/sprite/zenith
認證
請參閱認證頁面。需要 Bearer Token。
必要標頭：
Authorization: Bearer {your_api_key}
請求欄位
請以 multipart/form-data 傳送請求。每個檔案重複一次 images 欄位。
| 欄位名稱 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
| mode | string | 是 | 允許的值：image_to_video、first_last_frame、video_restyle | |
| images | file[] | 是 | image_to_video：恰好 1 個 PNG/JPEG。first_last_frame：恰好 2 個 PNG/JPEG（起始、結束）。video_restyle：恰好 1 個來源，PNG 精靈圖表或 GIF | |
| text | string | 是，除非提供參考圖片 | "" | 描述動作的提示詞。會移除前後空白。在 video_restyle 中，僅當提供 reference_image 時才可為空 |
| frame | integer | 圖片模式為必填 | 幀數。允許的值：36、100。在 video_restyle 中必須省略（由來源推導，見下方） | |
| is_pixel | boolean | 否 | false | 像素風。如果附加圖片本身是像素風，請開啟此選項。在 video_restyle 中會被忽略（強制為 false） |
| is_prompt_enhancement | boolean | 否 | true | 提示詞優化。根據你輸入的內容，將提示詞優化為更適合生成精靈的形式。在 video_restyle 中會被忽略（強制為 false） |
| reference_image | file | 否（僅限 video_restyle） | 參考圖片（選填）。僅限 PNG。來源精靈的主體會被替換為此圖片 | |
| sprite_grid | string | 使用 PNG 圖表的 video_restyle | 描述 PNG 圖表如何切割的 JSON 物件，例如 {"columns": 6, "rows": 6}。每個值為 1–32，最多 120 幀。不可與 GIF 來源一起使用 |
Sprite To Sprite（video_restyle）規則
- 來源檔案： PNG 精靈圖表（需傳送
sprite_grid）或 GIF（不傳送sprite_grid）。GIF 最多 120 幀，且長度最多 10 秒。 - 幀數由來源推導，與網頁應用程式完全相同：來源長度超過 5 秒時產生 100 幀（25 代幣），否則產生 36 幀（9 代幣）。GIF 使用其實際播放長度；含
N幀的 PNG 圖表計為round(N × 3000 / 36)毫秒，因此 61 幀以上會使用 100 幀層級。 - 必須提供
text或reference_image（或兩者皆提供）。 - 上傳來源的副檔名取自其內容，因此即使檔名沒有副檔名也能偵測到 GIF。
回應
成功回應 (200 OK)：
{
"job_id": "uuid-string"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| job_id | string | 已建立作業的唯一識別碼。請使用取得作業狀態查詢結果 |
錯誤 / 驗證規則
| 情況 | HTTP 狀態 | 錯誤訊息 |
|---|---|---|
| 檔案不是有效的圖片或格式不被允許 | 400 | "Invalid image file" |
| frame 遺漏或不允許（圖片模式） | 400 | "frame should be one of 36, 100" |
在 video_restyle 中傳送了 frame | 400 | "frame is derived from the source for video_restyle; do not send it" |
| 該模式的圖片數量錯誤 | 400 | "image_to_video requires exactly one image" / "first_last_frame requires exactly two images (start, end)" / "video_restyle requires exactly one source image (PNG sprite sheet or GIF)" |
| text 為空（圖片模式） | 400 | "text must not be empty" |
text 為空且沒有參考圖片（video_restyle） | 400 | "video_restyle requires text when no reference_image is given" |
在 video_restyle 以外傳送了 reference_image 或 sprite_grid | 400 | "reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle" |
| PNG 圖表未附 sprite_grid | 400 | "sprite_grid is required for a PNG sprite sheet" |
| GIF 附帶 sprite_grid | 400 | "sprite_grid is not allowed for a GIF source" |
| sprite_grid 格式錯誤或超出範圍 | 400 | sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames) |
| GIF 超過 120 幀 | 400 | "GIF must have at most 120 frames" |
| GIF 長度超過 10 秒 | 400 | "GIF must be at most 10 seconds long" |
| 無效的 API 金鑰 | 401 | "Invalid API key" |
| 欄位遺漏或未知的 mode | 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/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=running animation cycle" \
-F "frame=36" \
-F "is_pixel=true"
cURL (開始/結束參考圖片)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=first_last_frame" \
-F "images=@/path/to/start.png" \
-F "images=@/path/to/end.png" \
-F "text=turn around" \
-F "frame=100"
cURL (Sprite To Sprite，PNG 圖表附網格與參考圖片)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite_sheet.png" \
-F 'sprite_grid={"columns": 6, "rows": 6}' \
-F "reference_image=@/path/to/new_character.png"
cURL (Sprite To Sprite，GIF 附提示詞)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "text=a knight in silver armor"