Generate Effects V1

Purpose

Generates an effect sprite sheet asynchronously from a text description. You can optionally upload a reference image to guide the effect, and choose the output resolution and the sheet's background color. This is the same feature as the V1 tab of the web app's "Generate effects" page (the web app opens on the V2 tab by default).

Credit cost: 5 (1K), 7 (2K), 10 (4K)

Method and Path

POST /public/v1/generate/effect/v1

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
description	string	Yes	Effect description. Leading and trailing whitespace is trimmed
resolution	string	Yes	Resolution. Allowed values: 1K, 2K, 4K
background_color	string	Yes	Background color of the sheet. Allowed values: white, chroma_green, magenta, light_gray, light_purple, dark_gray
image	file	No	Optional reference image (PNG or JPEG)

Background color values

Value	Label	Color
white	White	#FFFFFF
chroma_green	Chroma key green	#52FF60
magenta	Magenta	#FF4CFF
light_gray	Light gray	#A6A6A6
light_purple	Light purple	#866CFE
dark_gray	Dark gray	#6A6A6A

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
Image is not a valid PNG or JPEG file	400	"Invalid image file"
Invalid API key	401	"Invalid API key"
Missing field or unknown enum value	422	Validation error

Async Job Behavior

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

Status Flow: Pending → Succeed or Failed

Example Request

cURL (without image):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K" \
-F "background_color=white"

cURL (with image):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a neon cyberpunk effect" \
-F "resolution=2K" \
-F "background_color=chroma_green" \
-F "image=@/path/to/input.png"