Skip to main content
POST
Image Generations
Async endpoint. The request returns immediately with the job’s id; the actual generation runs in the background and is charged on success only.
minimax-image-01 is the only image model in the free tier, so it is the one an account that has never added credits can call. Every other image model needs a first top-up: until then it answers 402 with error.code: "model_requires_paid".

Request body

string
required
One of: minimax-image-01, gpt-image-2, gpt-image-2.5-flare, nano-banana-3-flash, recraft-v4, recraft-v4-pro, recraft-v4-vector, flux-2-pro, flux-kontext-pro, ideogram-v3. See Image Generation.
string
required
Text prompt describing the desired image. Maximum 4000 characters.
number
default:"1"
Number of images to generate. Range 1–4; a value outside it is clamped, not refused. Each image is billed at the model’s per-image rate. Ignored by flux-2-pro (per-megapixel billing — n=1 always).
string
"WIDTHxHEIGHT" (e.g. "1024x1024") or "auto". Only the WIDTHxHEIGHT form is read, and it picks the nearest of the canonical aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 21:9; the resolution is the model’s own for that aspect. An aspect string such as "16:9" is not parsed. "auto", an aspect string, or a ratio far from all six falls back to the model default, which is landscape 16:9 on recraft-v4, recraft-v4-pro, recraft-v4-vector and flux-2-pro (21:9 also becomes 16:9 there). On flux-2-pro the hold is sized from the WIDTHxHEIGHT you send, and the final charge from the megapixels of the image delivered, so the hold can be larger than the charge; the difference is refunded.
string
low, medium or high on gpt-image-2 and gpt-image-2.5-flare, which price each image by quality. auto, or omitting it, is billed as medium. On gpt-image-2.5-flare each reference image (image_url / image_urls) adds $0.012 once per request, and sizes above 1536 px on a side return 400 invalid_parameter.
string
HTTPS URL of a single source image. Required for flux-kontext-pro (image-edit model). Optionally accepted by flux-2-pro for image-to-image generation. Ignored by other text-to-image models. A flux-kontext-pro request without image_url (or image_urls) returns 400 image_url_required.
string[]
Array of HTTPS source image URLs for multi-reference blending. Up to 16 on gpt-image-2 and gpt-image-2.5-flare and up to 10 on every other model. On flux-2-pro the first 6 entries are processed at high fidelity, entries 7–10 act as supplementary composition guides. Models that take image input: flux-2-pro, flux-kontext-pro, gpt-image-2, gpt-image-2.5-flare, nano-banana-3-flash. When both image_url and image_urls are present, image_urls takes precedence. A longer array returns 400 too_many_references.
string
Client-supplied key to make the request safe to retry. Also accepted as an Idempotency-Key header. Keys longer than 128 characters are cut to 128. The key is scoped to your account, not to one API key: repeated POSTs from the same account with the same key return the same job — no duplicate charge, no duplicate generation.
object
Pass-through model-specific parameters (e.g. seed, style). Forwarded to the underlying provider, except the fields your price is based on or that are moderated (prompt, image count, size, duration, reference images): those always come from the top-level parameters, and provider quality tiers that are not priced separately run at the priced tier.

Response

202 Accepted for new jobs, 200 OK if the same idempotency_key is replayed. When all of your concurrent image slots are busy, the job waits in a queue instead, and the response is 200 OK with a short body. Poll it like any other job; the hold is placed when it leaves the queue.
string
Job ID. Use it to poll GET /v1/jobs/{id}.
string
One of: queued, pending, processing, succeeded, failed, refunded, expired.
number
Hold amount placed at submit time (USD). Refunded if the job fails.
number | null
Final billed amount once the job succeeds. null until then.
number | null
The part of the hold returned to your balance once it is released (USD). null until then.

Poll for the result

Same response shape. Poll every 1–2 seconds until status is succeeded, failed, refunded, or expired. Most images complete within 30 seconds; the runner times out at 5 minutes.
The output.url is a Kyma-hosted URL. The image is copied there so the link keeps working after the model’s own temporary link expires. Job responses also carry kind, capability, prompt, aspect_ratio, duration_s and is_shared.

List your jobs

Your jobs, newest first, in the same shape as above. kind is image, video or audio (optional); limit is 1–100 (default 20). The response is {"object": "list", "data": [...], "next_cursor", "has_more"}: pass next_cursor back as cursor for the next page.

Errors

Most errors have the shape {"error": {"message", "code"}}. Some also carry type. The 402 bodies also carry balance, required, topup_url and a details object at the top level, plus topup on model_requires_paid and insufficient_credits. When status becomes failed or refunded, no charge is made and the held funds are returned to your balance via a hold_release ledger entry.

Examples

Free-tier image

Works on the signup credit.
The examples below use models that need a first top-up.

Cinematic hero shot

Image edit with kontext

Multi-reference blend with FLUX.2 Pro

Native vector (SVG) output

The resulting output.url returns an SVG file (Content-Type: image/svg+xml) with editable paths and layers — open directly in Figma or Illustrator.

Idempotent retry

Replaying this exact request returns the same job — no new charge.