Skip to main content
Turn a text prompt into images with 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, and color_palette_id work with nano_banana_pro, nano_banana_2_1, and nano_banana_2. On nano_banana, imagen_4, seedream_4, or flux_1_pro they return 422 (with param set to the field) — they are never dropped, and the engine is never switched.
  • Other endpoints. This list applies to POST /images/generations (and the MCP generate_image tool). Magic Edit and img2img accept their own engine values: both accept nano_banana_pro, nano_banana_2, and nano_banana_2_1, and Magic Edit also accepts gemini and kontext.
  • Organizations restricted to trained models. Some organizations generate only with their trained models. For them, GET /images/models returns an empty data list with unavailable_reason: "organization_restricted", any engine returns 422, and a request must omit engine and pass at least one trained model (style_id, object_ids, person_ids, setting_ids) or a color_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 costs 5 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.