Sprite Pulsar
Purpose
Pulsar パイプラインで36フレームのスプライトアニメーションを生成します。ウェブアプリの「Sprite Pulsar」ページと同じ機能です。Sprite Zenithと同じ入力とモードを使用しますが、長さは36フレームに固定されており、プロンプト補正オプションはありません 。
| mode | ウェブのタブ | 入力 |
|---|---|---|
image_to_video | シングル画像 | 画像1枚 |
first_last_frame | 開始/終了参照画像 | 画像2枚: 開始フレームと終了参照画像をこの順で |
video_restyle | Sprite To Sprite | 既存のスプライト1つ (PNGスプライトシート + グリッド、またはGIF) と任意の参照画像 |
クレジット消費: 3 (image_to_video, first_last_frame)、4 (video_restyle)
Method and Path
POST /public/v1/sprite/pulsar
Authentication
認証ページを参照してください。Bearerトークンが必要です。
必須ヘッダー:
Authorization: Bearer {your_api_key}
Request Fields
リクエストは multipart/form-data で送信します。images フィールドはファイルごとに1回ずつ繰り返します。
| フィールド名 | タイプ | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
| mode | string | はい | 許可される値: image_to_video, first_last_frame, video_restyle | |
| images | file[] | はい | image_to_video: PNG/JPEG をちょうど1枚。first_last_frame: PNG/JPEG をちょうど2枚 (開始、終了)。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フレームです。
Response
成功レスポンス (200 OK):
{
"job_id": "uuid-string"
}
| フィールド | タイプ | 説明 |
|---|---|---|
| job_id | string | 作成されたジョブの一意識別子。Get Job Statusで結果を照会します |
Error / Validation Rules
| 状況 | 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" |
| sprite_gridのないPNGシート | 400 | "sprite_grid is required for a PNG sprite sheet" |
| sprite_gridを伴うGIF | 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 |
すべての検証はファイルのアップロード前に実行されます。
Async Job Behavior
このエンドポイントは非同期ジョブを作成します。リクエスト即座にjob_idを返し、実際のスプライト生成はバックグラウンドで進行します。
ポーリング方法:
- レスポンスで受け取った
job_idを保存します GET /public/v1/job/{job_id}をポーリングして状態を確認します- 状態が
Succeedになるとimage_urlsで結果を確認します (スプライトシートおよびGIF)
状態フロー: Pending → Succeed または Failed
Example Request
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"