Create an AI image generation job
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Unique key for safe retries of job creation requests.
8 - 128Body
Image generation request. Each model has its own accepted set of
quality and ratio values — see GET /v1/models/{model_id} for
the authoritative matrix.
Orientation cheatsheet: • 9:16 → vertical / portrait (TikTok, Reels, Shorts, Stories) • 16:9 → horizontal / landscape (YouTube, web hero) • 1:1 → square (Instagram feed)
Text prompt describing the image.
1 - 4096Image model. Per-model qualities: • nano-banana-pro / nano-banana-2 → 1K | 2K | 4K • flux-2-pro / flux-2 → 1K | 2K • ideogram-v3 → TURBO | BALANCED | QUALITY • grok-imagine → STANDARD | QUALITY • seedream-5-lite → basic | high • gpt-image-2 → 1K | 2K | 4K • gpt-image-1-5 → medium | high • nano-banana-2-lite, seedream-4-5, wan-2-7-pro, wan-2-7, qwen2, z-image → default
nano-banana-pro, nano-banana-2, nano-banana-2-lite, flux-2-pro, flux-2, seedream-4-5, seedream-5-lite, wan-2-7-pro, wan-2-7, ideogram-v3, grok-imagine, qwen2, gpt-image-2, gpt-image-1-5, z-image Model-specific quality. See model_id description for accepted values.
"1K"
Aspect ratio, validated PER MODEL: any ratio the model advertises in GET /v1/models/{model_id} is accepted (e.g. 4:5 on the nano-banana models). Unsupported ratios return 400 with the accepted list in the error message. Omit to use the model's default ratio.
1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9 "9:16"
One hosted reference image URL. SSRF-checked. Upload local files via POST /v1/assets first.
Compatibility alias for reference_image_url. The backend uses
only the FIRST URL in the array. Prefer the singular form.
Number of images to generate. grok-imagine ignores this and always returns 2–6 images per run.
1 <= x <= 4Optional content to avoid.
1024Response
Image generation accepted.
image_generation_job, video_generation_job, talking_avatar_job queued, processing, completed, failed, canceled 0 <= x <= 100
