Sprite Zenith
Purpose
Zenith パイプラインでスプライトアニメーションを生成します。ウェブアプリの「Sprite Zenith」ページと同じ機能で、その3つのモードに対応しています:
| mode | ウェブのタブ | 入力 |
|---|---|---|
image_to_video | シングル画像 | 画像1枚 |
first_last_frame | 開始/終了参照画像 | 画像2枚: 開始フレームと終了参照画像をこの順で |
video_restyle | Sprite To Sprite | 既存のスプライト1つ (PNGスプライトシート + グリッド、またはGIF) と任意の参照画像 |
クレジット消費: 9 (36フレーム)、25 (100フレーム)
Method and Path
POST /public/v1/sprite/zenith
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 が指定されている場合のみ空にできます |
| 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)ms として計算されるため、61フレーム以上は100フレームのティアになります。 textまたはreference_image(また は両方) を指定する必要があります。- アップロードされたソースのファイル拡張子は内容から判定されるため、ファイル名に拡張子がなくてもGIFとして検出されます。
Response
成功レスポンス (200 OK):
{
"job_id": "uuid-string"
}
| フィールド | タイプ | 説明 |
|---|---|---|
| job_id | string | 作成されたジョブの一意識別子。Get Job Statusで結果を照会します |
Error / Validation Rules
| 状況 | 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" |
| 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/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"