POST /images/generations, optionally
composing your organization’s trained style, object, person, and
setting models plus a color palette. Pass engine to pick the
text-to-image model; omit it to use the default, nano_banana_pro.
GET /images/models lists the engines you
can use with their limits and credits.
Engines
Every engine accepts
num_outputs from 1 to 4 and defaults to aspect_ratio
1:1 and resolution 1K. A ratio or resolution the engine does not support
returns 422 before any credits are charged — the request is never reshaped.
- Trained models and palettes.
style_id,object_ids,person_ids,setting_ids, andcolor_palette_idwork withnano_banana_pro,nano_banana_2_1, andnano_banana_2. Onnano_banana,imagen_4,seedream_4, orflux_1_prothey return422(withparamset to the field) — they are never dropped, and the engine is never switched. - Other endpoints. This list applies to
POST /images/generations(and the MCPgenerate_imagetool). Magic Edit and img2img accept their ownenginevalues: both acceptnano_banana_pro,nano_banana_2, andnano_banana_2_1, and Magic Edit also acceptsgeminiandkontext. - Organizations restricted to trained models. Some organizations generate
only with their trained models. For them,
GET /images/modelsreturns an emptydatalist withunavailable_reason: "organization_restricted", anyenginereturns422, and a request must omitengineand pass at least one trained model (style_id,object_ids,person_ids,setting_ids) or acolor_palette_id.
Asynchronous pattern
Generation is asynchronous.POST /images/generations returns 202 Accepted
immediately with a job id, status, and an estimated_credits figure. Poll
GET /images/generations/{id} until
status is completed (or failed/cancelled), then read the produced images —
each carries a presigned URL valid for 24 hours. A job whose outputs all failed
the compliance pipeline ends failed with error
delivery_blocked_compliance: <codes> (see
Compliance blocks). Pass a
webhook_url to be notified instead of polling (see Webhooks).
Credits
Each output costs5 credits at 1K, scaling with resolution (1K ×1, 2K ×2,
4K ×4) and multiplied by num_outputs — the same on every engine. Costs draw
from your organization’s pool; an exhausted pool returns 402. See
Pricing.
Quickstart
A full zero-to-image walkthrough with curl, Python, and TypeScript.