Create image generation (async)
Generate or edit images. Asynchronous — returns 202 with a job_id immediately; poll GET /v1/jobs/{id} for the result. Models: see GET /v1/models for the live image catalogue. Billed per image; failures are refunded in full.
Request
- Base URL: https://kymaapi.com/v1
- URL: https://kymaapi.com/v1/images/generations
- Auth: HTTP bearer
Request body
Image model ID. Pick by task: gpt-image-2 = best text-in-image (multilingual, logos, posters); gpt-image-2.5-flare = consistent characters from reference images, exact text-in-image; flux-2-pro = photoreal + multi-reference blend (up to 10 source images); recraft-v4-pro = print-ready 4MP design; recraft-v4-vector = native SVG output with editable paths; ideogram-v3 = typography specialist; recraft-v4 = #1 HF Arena daily default; flux-kontext-pro = image edit/inpaint (REQUIRES image_url); minimax-image-01 = sub-cent budget tier.
Natural-language description of the image. For text-in-image with gpt-image-2, quote the literal text you want rendered (e.g., 'a poster reading "Open Late Friday" in bold serif'). Server normalizes to NFC before length check so stacked-diacritic scripts (Vietnamese, Hindi, Arabic) measure correctly.
Number of images to generate. Billed per output image. gpt-image-2 supports up to 10; other models cap at 4. A request with n=4 books and bills 4× the per-image price.
Output dimensions as WIDTHxHEIGHT (e.g., 1024x1024, 1024x1536, 1536x1024, 2048x2048) or 'auto'. gpt-image-2 supports 1024x1024 / 1024x1536 / 1536x1024 / 2048x2048; values outside that enum snap to 1024x1024. gpt-image-2.5-flare supports 1024x1024 / 1024x1536 / 1536x1024 / auto; a side above 1536 returns 400 invalid_parameter. Recraft V4 and FLUX.2 Pro accept fal-style aspect enums (square_hd, landscape_16_9, portrait_4_3, etc.) which the gateway maps for you. For per-MP pricing models (flux-2-pro), bigger sizes cost more.
Consumed by gpt-image-2 and gpt-image-2.5-flare (ignored elsewhere). Sets the OpenAI quality tier and the per-image price: gpt-image-2 low=$0.009, medium=$0.072, high=$0.285; gpt-image-2.5-flare low=$0.009, medium=$0.019, high=$0.285, plus $0.012 per reference image (image_url / image_urls) once per request. The hold books the full amount up front. 'auto' or omitted bills medium.
HTTPS URL of a source image. REQUIRED for flux-kontext-pro (image edit). Optional for gpt-image-2 and gpt-image-2.5-flare, which edit from it as a reference (on gpt-image-2.5-flare each reference image adds $0.012).
Multi-reference input. gpt-image-2 and gpt-image-2.5-flare accept up to 16 HTTPS URLs (gpt-image-2.5-flare adds $0.012 per reference, once per request); flux-2-pro accepts up to 10 and blends them; other models up to 10. More than the model's cap returns 400 too_many_references. When both image_url and image_urls are present, image_urls wins.
Deduplication key. Resending the same request body with the same key within the retention window returns the existing job (200 OK with the original ImageJob), not a new charge. Safe to retry 5xx responses.
Pass-through to the underlying model. Validated upstream — invalid keys return 400 from the provider, not 500.
Response
Idempotent replay — same idempotency_key returns the existing job
Hold amount placed at submit time (USD), as the ledger holds it. null while the job is queued and nothing is held yet.
Final billed amount (USD) once the hold is released: what a successful job cost, 0 for a failed or refunded one. null until then.
The part of the hold returned to your balance (USD) once it is released. null until then.
Changes
No recorded changes to this operation across all 1 revision of this API.