Equip Variation

Purpose

Equips items from an item sheet onto a character base image and generates the equipped variations. This is the same feature as the web app's "Equip Variation" page.

Credit cost: 5

Method and Path

POST /public/v1/image-tune/equip-variation

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	Description
character_image	file	Yes	Character base image (PNG or JPEG)
item_sheet_image	file	Yes	Item sheet image (PNG or JPEG)
prompt	string	Yes	Prompt describing how to equip the items. Whitespace is trimmed and the prompt must not be empty

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"
prompt is empty	400	"prompt must not be empty"
Invalid API key	401	"Invalid API key"
Missing field	422	Validation error

Both images are validated before anything is uploaded, so a failed request never leaves partial uploads behind.

Async Job Behavior

This endpoint creates an asynchronous job. It immediately returns a job_id, and generation runs 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:

curl -X POST "https://api.aetherforgeai.com/public/v1/image-tune/equip-variation" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "character_image=@/path/to/character.png" \
-F "item_sheet_image=@/path/to/item_sheet.png" \
-F "prompt=equip the iron sword and the leather helmet"