Skip to main content
POST
Generate images

Authorizations

Authorization
string
header
required

An organization API key created in Settings → Team, sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string | null

Reuse the same value when retrying the same request; a repeat returns the original generation without charging again. Reusing it with a different body returns 409.

Maximum string length: 128

Body

application/json

Generate one or more images from a prompt and optional reference images.

prompt
string
required

Text prompt for image generation

aspect_ratio
string | null

Requested aspect ratio (e.g. 1:1, 16:9, 9:16)

generate_image_count
integer
default:1

Number of images to generate

gpt_image_preset
string | null

GPT Image aspect preset used to choose a concrete size

gpt_image_size
string | null

GPT Image concrete WxH size

idempotency_key
string | null

Client-supplied key (≤128 chars); a repeat with the same key returns the original generation without re-charging

Maximum string length: 128
image_background
string | null

OpenAI image background setting (transparent, opaque, auto)

image_quality
string | null

Image quality setting; per-model (low|medium|high|xhigh|max for GPT Image 2.5, 1K|2K|4K for Gemini). Defaults to the selected model's catalog default.

image_resolution
string | null

Image resolution tier when the selected model exposes one (for example 1k or 2k).

mask_image
string | null

Asset id from POST /v1/uploads or a generation output's asset_id. Optional mask image URL for inpainting/editing

model
string | null

AI model identifier (provider specific)

moderation
string | null

OpenAI moderation setting (auto, low)

negative_prompt
string | null

Optional negative prompt

output_format
string | null

OpenAI image output format (png, webp, jpeg)

project_id
string | null

Project scope for the generated asset (optional)

reference_images
string[] | null

Asset id from POST /v1/uploads or a generation output's asset_id. List of reference image URLs for image-to-image editing

reference_names
Reference Names · object | null

User-facing aliases for reference images, keyed by reference_images

response_format
string | null

OpenAI image response format (b64_json, url)

Response

Successful Response

One generation. Poll GET /v1/generations/{id} until status is completed or failed.

created_at
string<date-time>
required
id
string
required
Example:

"6f1c2d3e-9a0b-4c7d-8e1f-2a3b4c5d6e7f"

model
string
required
Example:

"seedance-2-5-fal"

prompt
string
required
status
enum<string>
required
Available options:
pending,
completed,
failed
type
enum<string>
required
Available options:
image,
video,
audio
completed_at
string<date-time> | null
credits_charged
number | null

Credits actually charged; null while pending.

error
GenerationError · object | null
idempotency_key
string | null
outputs
GenerationOutput · object[]