Sprite Zenith

Purpose

Generates a sprite animation with the Zenith pipeline. This is the same feature as the web app's "Sprite Zenith" page and supports its three modes:

mode	Web tab	Input
image_to_video	Single image	One image
first_last_frame	Start/end reference images	Two images: the start frame and the end reference image, in order
video_restyle	Sprite To Sprite	One existing sprite (PNG sprite sheet + grid, or GIF) and an optional reference image

Credit cost: 9 (36 frames), 25 (100 frames)

Method and Path

POST /public/v1/sprite/zenith

Authentication

See the Authentication page. Bearer token is required.

Required Headers:

Authorization: Bearer {your_api_key}

Request Fields

Send the request as multipart/form-data. Repeat the images field once per file.

Field Name	Type	Required	Default	Description
mode	string	Yes		Allowed values: image_to_video, first_last_frame, video_restyle
images	file[]	Yes		image_to_video: exactly 1 PNG/JPEG. first_last_frame: exactly 2 PNG/JPEG (start, end). video_restyle: exactly 1 source, PNG sprite sheet or GIF
text	string	Yes, except with a reference image	""	Prompt describing the motion. Whitespace is trimmed. In video_restyle it may be empty only when reference_image is given
frame	integer	Yes for image modes		Frames. Allowed values: 36, 100. Must be omitted in video_restyle (derived from the source, see below)
is_pixel	boolean	No	false	Pixel art. Turn this on if the attached image is based on pixel art. Ignored (forced false) in video_restyle
is_prompt_enhancement	boolean	No	true	Prompt enhancement. Refines your input to make it more suitable for sprite generation. Ignored (forced false) in video_restyle
reference_image	file	No (video_restyle only)		Reference image (optional). PNG only. The subject of the source sprite is replaced with this image
sprite_grid	string	video_restyle with a PNG sheet		JSON object describing how the PNG sheet is cut, e.g. {"columns": 6, "rows": 6}. Each value 1–32, at most 120 frames. Not allowed with a GIF source

Sprite To Sprite (video_restyle) rules

• Source file: a PNG sprite sheet (send sprite_grid) or a GIF (no sprite_grid). The GIF may have at most 120 frames and be at most 10 seconds long.
• The frame count is derived from the source, exactly like the web app: a source longer than 5 seconds produces 100 frames (25 credits), otherwise 36 frames (9 credits). A GIF uses its real playback length; a PNG sheet with N frames counts as round(N × 3000 / 36) ms, so 61 frames or more use the 100-frame tier.
• text or reference_image (or both) must be given.
• The file extension of the uploaded source is taken from its content, so a GIF is detected even if the filename has no extension.

Response

Success Response (200 OK):

{
  "job_id": "uuid-string"
}

Field	Type	Description
job_id	string	Unique identifier for the created job. Use Get Job Status to retrieve results

Error / Validation Rules

Condition	HTTP Status	Error Message
A file is not a valid image or has a disallowed format	400	"Invalid image file"
frame missing or not allowed (image modes)	400	"frame should be one of 36, 100"
frame sent in video_restyle	400	"frame is derived from the source for video_restyle; do not send it"
Wrong number of images for the mode	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 empty (image modes)	400	"text must not be empty"
text empty and no reference image (video_restyle)	400	"video_restyle requires text when no reference_image is given"
reference_image or sprite_grid sent outside video_restyle	400	"reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle"
PNG sheet without sprite_grid	400	"sprite_grid is required for a PNG sprite sheet"
GIF with sprite_grid	400	"sprite_grid is not allowed for a GIF source"
sprite_grid malformed or out of range	400	sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames)
GIF has more than 120 frames	400	"GIF must have at most 120 frames"
GIF longer than 10 seconds	400	"GIF must be at most 10 seconds long"
Invalid API key	401	"Invalid API key"
Missing field or unknown mode	422	Validation error

All validation runs before any file is uploaded.

Async Job Behavior

This endpoint creates an asynchronous job. It immediately returns a job_id, and actual sprite generation occurs in the background.

Polling Method:

1. Save the job_id received in the response
2. Poll GET /public/v1/job/{job_id} to check status
3. When status becomes Succeed, check results in image_urls (sprite sheet and GIF)

Status Flow: Pending → Succeed or Failed

Example Request

cURL (Single image):

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 (Start/end reference images):

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 sheet with grid and reference image):

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 with prompt):

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"