Sprite Pulsar
用途
使用 Pulsar 流程生成 36 幀的精靈動畫。此功能與網頁應用程式「Sprite Pulsar」頁面相同。它使用與 Sprite Zenith 相同的輸入與模式，但長度固定為 36 幀，且沒有提示詞優化選項。
| mode | 網頁分頁 | 輸入 |
|---|---|---|
image_to_video | 單張圖片 | 一張圖片 |
first_last_frame | 開始/結束參 考圖片 | 兩張圖片：依序為起始幀與結束參考圖片 |
video_restyle | Sprite To Sprite | 一個現有精靈（PNG 精靈圖表 + 網格，或 GIF）以及可選的參考圖片 |
代幣消耗： 3（image_to_video、first_last_frame）、4（video_restyle）
方法與路徑
POST /public/v1/sprite/pulsar
認證
請參閱認證頁面。需要 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 時才可為空 |
| is_pixel | boolean | 否 | false | 像素風。如果附加圖片本身是像素風，請開啟此選項。在 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）的來源規則與 Sprite Zenith 相同：PNG 圖表 + sprite_grid，或最多 120 幀、10 秒的 GIF。沒有 frame 欄位；輸出固定為 36 幀。
回應
成功回應 (200 OK)：
{
"job_id": "uuid-string"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| job_id | string | 已建立作業的唯一識別碼。請使用取得作業狀態查詢結果 |
錯誤 / 驗證規則
| 情況 | HTTP 狀態 | 錯誤訊息 |
|---|---|---|
| 檔案不是有效的圖片或格式不被允許 | 400 | "Invalid image file" |
| 該模式的圖片數量錯誤 | 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/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=idle breathing" \
-F "is_pixel=true"
cURL (開始/結束參考圖片)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-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=draw the sword"
cURL (Sprite To Sprite，GIF 附參考圖片)：
curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "reference_image=@/path/to/new_character.png"