Sprite Plus

Purpose

Generates a sprite animation from a start frame and an optional end frame. This is the same feature as the Plus tab of the web app's "Generate sprites" page (Sprite Lite & Plus). Choose the number of frames with frame, exactly as shown on the web page's slider.

Credit cost: 9 (49 frames), 13 (81 frames)

Method and Path

POST /public/v1/sprite/plus

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.

Field Name	Type	Required	Default	Description
start_image	file	Yes		Start frame (PNG or JPEG)
end_image	file	No		End frame (optional) (PNG or JPEG)
text	string	Yes		Prompt describing the motion. Whitespace is trimmed and the text must not be empty
frame	integer	Yes		Frames. Allowed values: 49, 81
is_pixel	boolean	No	false	Pixel art. Turn this on if the attached image is based on pixel art
is_prompt_enhancement	boolean	No	true	Prompt enhancement. Refines your input to make it more suitable for sprite generation

Credits by frame

frame	Credits
49	9
81	13

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
Either image is not a valid PNG or JPEG file	400	"Invalid image file"
frame value is not allowed	400	"frame should be one of 49, 81"
text is empty	400	"text must not be empty"
Invalid API key	401	"Invalid API key"
Missing field	422	Validation error

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 (start frame only):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/plus" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "start_image=@/path/to/character.png" \
-F "text=walking animation" \
-F "frame=49" \
-F "is_pixel=true"

cURL (start + end frame):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/plus" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "start_image=@/path/to/character_start.png" \
-F "end_image=@/path/to/character_end.png" \
-F "text=running animation cycle" \
-F "frame=81"