Skip to main content
POST
Create an AI image generation job

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Unique key for safe retries of job creation requests.

Required string length: 8 - 128

Body

application/json

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)

prompt
string
required

Text prompt describing the image.

Required string length: 1 - 4096
model_id
enum<string>
required

Image 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

Available options:
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
quality
string

Model-specific quality. See model_id description for accepted values.

Example:

"1K"

ratio
enum<string>
default:1:1

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.

Available options:
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
Example:

"9:16"

reference_image_url
string<uri>

One hosted reference image URL. SSRF-checked. Upload local files via POST /v1/assets first.

reference_image_urls
string<uri>[]
deprecated

Compatibility alias for reference_image_url. The backend uses only the FIRST URL in the array. Prefer the singular form.

count
integer
default:1

Number of images to generate. grok-imagine ignores this and always returns 2–6 images per run.

Required range: 1 <= x <= 4
negative_prompt
string

Optional content to avoid.

Maximum string length: 1024

Response

Image generation accepted.

id
string
required
object
enum<string>
required
Available options:
image_generation_job,
video_generation_job,
talking_avatar_job
status
enum<string>
required
Available options:
queued,
processing,
completed,
failed,
canceled
credits_reserved
integer
required
assets
object[]
required
created_at
string<date-time>
required
progress_percent
integer | null
Required range: 0 <= x <= 100
credits_used
integer | null
credits_refunded
integer
default:0
request
object
failure_code
string | null
failure_message
string | null
updated_at
string<date-time> | null
completed_at
string<date-time> | null
failed_at
string<date-time> | null