Skip to main content
POST
/
images
/
generations
Generate images from a prompt (and optional trained models)
curl --request POST \
  --url https://api.samsa.ai/public/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "person_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "setting_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "engine": "nano_banana_pro",
  "num_outputs": 1,
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "output_format": "png",
  "webhook_url": "https://example.com/webhooks/samsa"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}
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 — style_id, object_ids, person_ids, setting_ids, and color_palette_id.

​
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 id must reference a completed model in your organization. 
curl -X POST https://api.samsa.ai/public/v1/images/generations \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Our founder presenting on stage at the product launch, cinematic lighting",
    "style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
    "person_ids": ["c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
    "setting_ids": ["a9b8c7d6-e5f4-4a3b-2c1d-0e1f2a3b4c5d"],
    "color_palette_id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
    "engine": "nano_banana_pro",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "num_outputs": 2
  }'
object_ids, person_ids, and setting_ids are arrays; style_id and color_palette_id are single ids. num_outputs (1–4) defaults to 1 and each output is billed. Omit engine to use the default nano_banana_pro.

Authorizations

​
Authorization
string
header
required

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

Headers

​
authorization
string | null

Body

application/json

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

Trained-model refs (style_id, object_ids, person_ids, setting_ids, color_palette_id) combine on the Gemini path; setting_ids maps to the internal scene_ids (ADR §8.2). engine is a public-safe subset of the image engines (ADR §8.3). 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
string<uuid> | null

A style model in your organization (must be completed).

​
object_ids
string<uuid>[]

object models in your organization to compose in.

​
person_ids
string<uuid>[]

person models in your organization to compose in.

​
setting_ids
string<uuid>[]

setting models in your organization (maps to internal scenes).

​
color_palette_id
string<uuid> | null

A color palette in your organization.

​
engine
string | null

Generation engine — one of nano_banana_pro (default) or nano_banana_2. Omit to use the default. Unknown engines return 422.

Example:

"nano_banana_pro"

​
num_outputs
integer
default:1

Number of images to generate (1-4). 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).

Example:

"1:1"

​
resolution
string
default:1K

Output resolution — 1K, 2K, or 4K. Credits scale 1K:1x, 2K:2x, 4K:4x per output.

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