Skip to main content
POST
Image Generations
Async endpoint. The request returns immediately with a job_id; the actual generation runs in the background and is charged on success only.

Request body

model
string
required
One of: recraft-v4, recraft-v4-pro, recraft-v4-vector, recraft-v4-vector-pro, flux-2-pro, flux-kontext-pro, ideogram-v3, flux-1.1-ultra (legacy), recraft-v3 (legacy). See Image Generation.
prompt
string
required
Text prompt describing the desired image. Maximum 4000 characters.
n
number
default:"1"
Number of images to generate. Range 1–4. Each image is billed at the model’s per-image rate. Ignored by flux-2-pro (per-megapixel billing — n=1 always).
size
string
Output dimensions or aspect ratio. Accepted forms: "auto", "WIDTHxHEIGHT" (e.g. "1024x1024"), or an aspect string like "16:9". Mapped to one of the canonical aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Unrecognized sizes use the model default. For flux-2-pro, larger sizes increase the per-megapixel charge.
image_url
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.
image_urls
string[]
Array of up to 10 HTTPS source image URLs for multi-reference blending. Currently supported by flux-2-pro only — first 6 entries are processed at high fidelity, entries 7–10 act as supplementary composition guides. When both image_url and image_urls are present, image_urls takes precedence. Arrays longer than 10 return 400 too_many_references.
idempotency_key
string
Client-supplied key (≤128 chars) to make the request safe to retry. Repeated POSTs with the same (api_key, idempotency_key) pair return the same job — no duplicate charge, no duplicate generation.
extra
object
Pass-through model-specific parameters (e.g. seed, style). Forwarded to the underlying provider unchanged.

Response

202 Accepted for new jobs, 200 OK if the same idempotency_key is replayed.
id
string
Job ID. Use it to poll GET /v1/jobs/{id}.
status
string
One of: pending, processing, succeeded, failed, refunded, expired.
estimated_cost
number
Hold amount placed at submit time (USD). Refunded if the job fails.
charged_amount
number | null
Final billed amount once the job succeeds. 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 points to a Vercel Blob URL hosted by Kyma — the original upstream URL is rehosted so it remains stable after the upstream TTL expires.

Errors

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

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.