Character Overlay V1

Purpose

Overlays character images onto a sprite sheet to generate a new sprite. Used when compositing characters onto a background sprite sheet.

Method and Path

POST /public/v1/sprite/character-overlay/v1

Authentication

See the Authentication page. Bearer token is required.

Required Headers:

Authorization: Bearer {your_api_key}

Request Fields

Field Name	Type	Required	Description
sprite_sheet	file	Yes	Sprite sheet image file to serve as the reference
character_images	file[]	Yes	Character image files to overlay. 1 to 4 files can be uploaded
rows	string	Yes	JSON string containing row information. Each row must include row, title, and description
resolution	string	Yes	Output resolution. Possible values: 1K, 2K, 4K
style	string	No	Style specification (optional). Possible values: pixel, cartoon, sd, quater_view

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
Invalid image file	400	"Invalid image file"
character_images is less than 1 or more than 4	400	"character_images must contain between 1 and 4 files"
character_images field is missing	422	Field required
rows is not valid JSON	400	"rows must be a valid JSON list"
rows is not a list	400	"rows must be a JSON list"
Row missing required keys	400	"each row must be an object with row, title, description"
row is not an integer	400	"row must be an integer"
title or description is not a string	400	"title and description must be strings"
resolution value is invalid	422	Values other than 1K, 2K, 4K will result in validation error
Authentication failed	401	Invalid API key

rows JSON Format:

[
  {
    "row": 1,
    "title": "Idle",
    "description": "Character standing still"
  },
  {
    "row": 2,
    "title": "Walk",
    "description": "Character walking animation"
  }
]

Async Job Behavior

This endpoint creates an asynchronous job. It immediately returns a job_id, and actual overlay processing 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

Status Flow: Pending → Succeed or Failed

Example Request

cURL (Single Character):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "sprite_sheet=@/path/to/background_sprite.png" \
-F "character_images=@/path/to/character.png" \
-F 'rows=[{"row":1,"title":"Idle","description":"Standing"},{"row":2,"title":"Walk","description":"Walking"}]' \
-F "resolution=2K"

cURL (Multiple Characters):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "sprite_sheet=@/path/to/background_sprite.png" \
-F "character_images=@/path/to/char1.png" \
-F "character_images=@/path/to/char2.png" \
-F "character_images=@/path/to/char3.png" \
-F 'rows=[{"row":1,"title":"Scene1","description":"First scene"},{"row":2,"title":"Scene2","description":"Second scene"}]' \
-F "resolution=2K" \
-F "style=pixel"