Sprite Pulsar

Purpose

Generates a 36-frame sprite animation with the Pulsar pipeline. This is the same feature as the web app's "Sprite Pulsar" page. It uses the same inputs and modes as Sprite Zenith, but the length is fixed at 36 frames and there is no prompt enhancement option.

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: 3 (image_to_video, first_last_frame), 4 (video_restyle)

Method and Path

POST /public/v1/sprite/pulsar

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
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
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

The Sprite To Sprite (video_restyle) source rules are the same as for Sprite Zenith: PNG sheet + sprite_grid, or a GIF with at most 120 frames and 10 seconds. There is no frame field; the output is always 36 frames.

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

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

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"