Generate Image

Purpose

Generates AI images based on text prompts. You can optionally upload reference images to guide the style or composition of the generated results.

Method and Path

POST /public/v1/generate/image

Authentication

See the Authentication page. Bearer token is required.

Required Headers:

Authorization: Bearer {your_api_key}

Request Fields

Field Name	Type	Required	Description
prompt	string	Yes	Text prompt for image generation
ai_model	string	Yes	AI model to use. Possible values: GPT Image 1.5, GPT Image 2, GPT Image 2.5 High, GPT Image 2.5 XHigh, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2, Nano Banana Pro (deprecated: GPT Image 1.5, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2)
ref_images	file[]	No	Reference image files (multipart/form-data). Maximum upload count varies by AI model

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"
ref_images exceeds 5 for Grok Imagine model	400	"The Grok Imagine model supports up to 5 ref_images."
ref_images exceeds 1 for Grok Imagine Pro model	400	"The Grok Imagine Pro model supports up to 1 ref_images."
ref_images exceeds 10 for other models	400	"ref_images supports up to 10 images only"
Authentication failed	401	Invalid API key

Reference Image Limits:

• GPT Image 1.5: Maximum 10
• GPT Image 2 / 2.5 High / 2.5 XHigh: Maximum 10
• Grok Imagine: Maximum 5
• Grok Imagine Pro: Maximum 1
• Nano Banana series: Maximum 10

Async Job Behavior

This endpoint creates an asynchronous job. It immediately returns a job_id, and actual image 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 reference images):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a beautiful sunset over mountains" \
-F "ai_model=GPT Image 1.5"

cURL (with reference images):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a cat in the style of the reference" \
-F "ai_model=Grok Imagine" \
-F "ref_images=@/path/to/ref1.jpg" \
-F "ref_images=@/path/to/ref2.jpg"