Skip to main content
POST
Generate images from a prompt (and optional trained models)
Submit a prompt to generate one to four images. The call returns 202 Accepted with a job id; poll GET /images/generations/{id} for the result. Combine your organization’s trained models by passing their ids or names — style_id, object_ids, person_ids, setting_ids — plus a color_palette_id. Each ref accepts a name or id that resolves to a model or palette visible to you. Pick the text-to-image model with engine — list the engines you can use with GET /images/models.

Example: compose multiple trained models

Pass a style model, one or more person and setting models, and a color palette together in one request. Every model reference — by id or name — must resolve to a completed model visible to you.
object_ids, person_ids, and setting_ids are arrays; style_id and color_palette_id take a single value (a name or id). num_outputs (1–4) defaults to 1 and each output is billed. Omit engine to use the default nano_banana_pro, or pass nano_banana_2_1, nano_banana_2, nano_banana, imagen_4, seedream_4, or flux_1_pro. Each engine has its own aspect ratios and resolutions — see Engines or GET /images/models; an unsupported value returns 422 before any credits are charged. Trained models and color_palette_id work only with nano_banana_pro, nano_banana_2_1, and nano_banana_2; other engines return 422.

Authorizations

Authorization
string
header
required

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Body

application/json

POST /images/generations body (ADR §8, §10).

Trained-model refs (style_id, object_ids, person_ids, setting_ids) and the color_palette_id color-palette ref combine on the Gemini engines — each accepts a NAME or its UUID id, resolved within your visible set (a model/palette you own, including private ones, or a non-private one shared within your organization); setting_ids maps to the internal scene_ids (ADR §8.2). The standalone engines (nano_banana, imagen_4, seedream_4, flux_1_pro) reject refs with a 422. engine is the public text-to-image catalog (ADR §8.3, GET /images/models). Note num_outputs defaults to 1 for API ergonomics — the internal app default is 4.

prompt
string
required

Text prompt. Runs the same validation as the app (rejects empty / malformed / policy-violating prompts with a 422).

Minimum string length: 1
Example:

"A minimalist product shot of a ceramic mug on linen, soft daylight"

style_id

A style model NAME or its UUID id (from list_models), resolved within your visible set — a model you own (including your own private models) or a non-private one shared with your organization. A name matching more than one visible model is rejected — pass the id. Must be completed.

object_ids
(string<uuid> | string)[]

object models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.

person_ids
(string<uuid> | string)[]

person models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.

setting_ids
(string<uuid> | string)[]

setting models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id. Maps to internal scenes.

color_palette_id

A color palette NAME or its UUID id, resolved within your visible set — a palette you created (including private ones) or a non-private palette shared with your organization. A name matching more than one visible palette is rejected — pass the id.

engine
string | null

Generation engine — one of nano_banana_pro (Nano Banana Pro, default), nano_banana_2_1 (Nano Banana 2.1), nano_banana_2 (Nano Banana 2), nano_banana (Nano Banana), imagen_4 (Imagen 4), seedream_4 (Seedream 4), flux_1_pro (Flux.1 Pro). Omit to use the default. Each engine has its own aspect ratios and resolutions — list them with GET /images/models. Trained models (style_id, object_ids, person_ids, setting_ids) work only with nano_banana_pro, nano_banana_2_1, nano_banana_2, and color_palette_id only with nano_banana_pro, nano_banana_2_1, nano_banana_2; other engines return 422 (refs are never dropped and the engine is never switched). Unknown engines return 422. Some organizations generate only with their trained models: there any engine returns 422 — omit it and pass at least one trained model or a color_palette_id. Compatibility note (2026-10): nano_banana keeps its engine id, limits and price, but now runs on the Google API like every Nano Banana engine (it ran on FAL before). Its outputs take the same provenance and labelled-download path as all other generations.

Example:

"nano_banana_pro"

num_outputs
integer
default:1

Number of images to generate (1-4, every engine). Defaults to 1 (the app default is 4); each output is billed.

Required range: 1 <= x <= 4
Example:

1

aspect_ratio
string
default:1:1

Aspect ratio for the generated image(s), 1:1 (default). Valid values depend on the engine (see aspect_ratios in GET /images/models): nano_banana_pro/nano_banana_2_1/nano_banana_2: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8; nano_banana: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9; imagen_4: 1:1, 16:9, 9:16, 4:3, 3:4; seedream_4/flux_1_pro: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Unsupported ratios return 422 before any credits are charged.

Example:

"1:1"

resolution
string
default:1K

Output resolution, 1K (default). Valid values depend on the engine (see resolutions in GET /images/models): nano_banana_pro/nano_banana_2_1/nano_banana_2: 1K, 2K, 4K; nano_banana/seedream_4/flux_1_pro: 1K; imagen_4: 1K, 2K. Credits scale 1K:1x, 2K:2x, 4K:4x per output; unsupported values return 422 before any credits are charged.

Example:

"1K"

output_format
enum<string>
default:png

Encoding of the returned images. v1 supports png only.

Available options:
png
Example:

"png"

webhook_url
string | null

Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).

Example:

"https://example.com/webhooks/samsa"

Response

Successful Response

202 body for POST /images/generations (ADR §7.1).

id
string<uuid>
required

The image job id — poll GET /images/generations/{id}.

status
enum<string>
required

Initial status: always pending at submit.

Available options:
pending,
processing,
completed,
failed,
cancelled
Example:

"pending"

estimated_credits
integer
required

Credits this job is expected to cost (base 5 x num_outputs x resolution multiplier).

Example:

5