Generate an Image

POST/v1/images/generations

Overview

Generate one square 1k image through a direct xAI, fal or MiniMax endpoint.

Routing and provider details

Requires an explicitly scoped images.write API key, credits, and an enabled IMAGES_ENABLED deployment. Also accepts /api/v1/images/generations. Integration preview until deployed staging acceptance.

Idempotency-Key is required. One durable request authorizes one native generation; duplicate submissions return status and never regenerate. Output bytes are returned once and are not retained for replay. Native monetary usage determines the charge. A temporary wallet hold covers the reviewed maximum; unresolved requests retain their hold. A known failed output records provider expense without a customer charge.

The initial profile supports a 1024-byte UTF-8 prompt, n=1, resolution=1k, aspect_ratio=1:1 and response_format=b64_json. Image 2.0 uses low quality. Direct fal FLUX profiles generate one 1024x1024 PNG with the safety checker enabled. Returned native billable units determine the charge at the published megapixel rate; no output URL is fetched. MiniMax image-01 uses one 1024x1024 base64 image, prompt optimization off, and its native successful-image count at the published per-image rate. Editing, input images, provider storage and arbitrary controls are excluded. Workspace limits are 20 requests per minute, four pending requests and $5 of provider expense/exposure per day; older unresolved holds still count.

Authorization

Authorizationstring · headerRequired

AudioLab API key sent as Bearer <token>. Authentication guide

Parameters

Idempotency-Keyheader · stringRequired

Request Body

application/json

providerobject

Provider preferences for a single-endpoint product.

Show nested fields

data_regionstring | string[]

Route only to endpoints documented as processing in this region: us, eu (which includes EU member states), or a country code such as nl, sg, in or cn. A list matches any of its regions. Endpoints whose region is global or unknown never match; global on its own means no requirement. The request's region narrows the workspace's Data Region and a named router's region policy, and never widens them. Fallbacks keep to it. When no endpoint qualifies, the request is refused with 400 data_region_unavailable, param provider.data_region.

Show nested fields

Option 1: string

string

Option 2: string[]

See the OpenAPI schema for this nested object.

modelstringRequired

Values: "xai/grok-imagine-image""xai/grok-imagine-image-2026-03-02""xai/grok-imagine-image-2.0""xai/grok-imagine-image-quality""xai/grok-imagine-image-quality-20260403""xai/grok-imagine-image-quality-latest""xai/grok-imagine-image-pro""fal/fal-ai/flux/schnell""fal/fal-ai/flux/dev""fal/fal-ai/flux-1/krea""fal/fal-ai/flux-2""minimax/image-01"

promptstringRequired

ninteger

Default: 1

resolutionstring

Default: "1k"

aspect_ratiostring

Default: "1:1"

response_formatstring

Default: "b64_json"

Responses

200Validated image with committed accounting.

application/json

createdintegerRequired

modelstringRequired

dataobject[]Required

Show nested fields

b64_jsonstringRequired

mime_typestringRequired

Values: "image/png""image/jpeg""image/webp"

usageobjectRequired

Show nested fields

imagesinteger

coststring

Customer charge in USD.

400Missing or invalid idempotency key.

401Invalid API key.

402Insufficient credits for the reviewed hold.

403Scope, privacy or spend-limit restriction.

409Request already exists or idempotency ownership conflicts; no regeneration.

422Invalid or unsupported model or input.

429Workspace generation limit reached.

502Known provider expense but unusable output; customer charge waived.

503Disabled contract, unresolved expense or provider cap review; inspect request status.