> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate images
> Submit an image-generation job — prompt plus optional trained models — and get a job id back.
Submit a prompt to generate one to four images. The call returns **`202 Accepted`**
with a job `id`; poll [`GET /images/generations/{id}`](/api-reference/images/get-generation)
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.
```bash curl theme={null}
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
}'
```
```json Body theme={null}
{
"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`.
## OpenAPI
````yaml api-reference/openapi.json POST /images/generations
openapi: 3.1.0
info:
title: Samsa API
description: >-
The Samsa public REST API. Authenticate with an organization API key as a
bearer token (`Authorization: Bearer samsa_sk_...`). Errors follow a single
envelope shape; every response carries an `X-Request-ID`.
version: 1.0.0
servers:
- url: https://api.samsa.ai/public/v1
security:
- BearerAuth: []
paths:
/images/generations:
post:
tags:
- Images
summary: Generate images from a prompt (and optional trained models)
description: >-
Submits an image-generation job and returns `202` immediately with the
job `id` and a credit estimate; poll `GET /images/generations/{id}` for
the result. Combine a `prompt` with your organization's trained models
(`style_id`, `object_ids`, `person_ids`, `setting_ids`) and an optional
`color_palette_id`. `num_outputs` defaults to **1** (the app default is
4); each output is billed at `5 x resolution_multiplier` credits (1K:1x,
2K:2x, 4K:4x). Requires the `images.generate` scope.
operationId: create_image_generation_images_generations_post
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicImageGenerationRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicImageGenerationAccepted'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'402':
description: Insufficient credits, or no usable org subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: The API key lacks the required scope for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Generation, or a referenced model/palette, not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: A referenced model is not ready for generation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Request validation failed (prompt, engine, resolution, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Per-key rate limit or per-org concurrency cap exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
PublicImageGenerationRequest:
properties:
prompt:
type: string
minLength: 1
title: Prompt
description: >-
Text prompt. Runs the same validation as the app (rejects empty /
malformed / policy-violating prompts with a `422`).
examples:
- A minimalist product shot of a ceramic mug on linen, soft daylight
style_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Style Id
description: A `style` model in your organization (must be `completed`).
object_ids:
items:
type: string
format: uuid
type: array
title: Object Ids
description: '`object` models in your organization to compose in.'
person_ids:
items:
type: string
format: uuid
type: array
title: Person Ids
description: '`person` models in your organization to compose in.'
setting_ids:
items:
type: string
format: uuid
type: array
title: Setting Ids
description: '`setting` models in your organization (maps to internal scenes).'
color_palette_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Color Palette Id
description: A color palette in your organization.
engine:
anyOf:
- type: string
- type: 'null'
title: Engine
description: >-
Generation engine — one of `nano_banana_pro` (default) or
`nano_banana_2`. Omit to use the default. Unknown engines return
`422`.
examples:
- nano_banana_pro
num_outputs:
type: integer
maximum: 4
minimum: 1
title: Num Outputs
description: >-
Number of images to generate (1-4). Defaults to **1** (the app
default is 4); each output is billed.
default: 1
examples:
- 1
aspect_ratio:
type: string
title: Aspect Ratio
description: Aspect ratio for the generated image(s).
default: '1:1'
examples:
- '1:1'
resolution:
type: string
title: Resolution
description: >-
Output resolution — `1K`, `2K`, or `4K`. Credits scale 1K:1x, 2K:2x,
4K:4x per output.
default: 1K
examples:
- 1K
output_format:
$ref: '#/components/schemas/PublicImageOutputFormat'
description: Encoding of the returned images. v1 supports `png` only.
default: png
examples:
- png
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Optional https webhook notified once on terminal status (signed per
the webhook signature scheme; see the webhooks docs).
examples:
- https://example.com/webhooks/samsa
type: object
required:
- prompt
title: PublicImageGenerationRequest
description: >-
`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.
PublicImageGenerationAccepted:
properties:
id:
type: string
format: uuid
title: Id
description: The image job id — poll `GET /images/generations/{id}`.
status:
$ref: '#/components/schemas/PublicImageStatus'
description: 'Initial status: always `pending` at submit.'
examples:
- pending
estimated_credits:
type: integer
title: Estimated Credits
description: >-
Credits this job is expected to cost (base 5 x num_outputs x
resolution multiplier).
examples:
- 5
type: object
required:
- id
- status
- estimated_credits
title: PublicImageGenerationAccepted
description: '`202` body for `POST /images/generations` (ADR §7.1).'
ErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorEnvelope
description: The complete public error body — an ``error`` object wrapper (ADR §5).
PublicImageOutputFormat:
type: string
enum:
- png
title: PublicImageOutputFormat
description: >-
Public output format for generated images.
v1 exposes ``png`` only: both public engines route through the Gemini
path,
which reliably returns PNG and does NOT convert to ``jpeg``/``webp`` (it
would
accept the request, charge, and still return PNG — a misleading
contract). The
other formats are deferred until the generation path converts them
(SAM-623).
PublicImageStatus:
type: string
enum:
- pending
- processing
- completed
- failed
- cancelled
title: PublicImageStatus
description: >-
Public image-job status — the lower-cased internal ``TaskStatus``.
Deliberately the plain lower-cased internal value (NOT the ADR §7.2
``PENDING -> queued`` remap): the ticket's 202 uses ``status:
"pending"`` and
its fixtures say ``pending/processing/completed/failed``, and this keeps
the
public surface consistent with the already-shipped models API
(``PublicModelStatus``).
ErrorDetail:
properties:
type:
type: string
title: Type
examples:
- authentication_error
code:
type: string
title: Code
examples:
- invalid_api_key
message:
type: string
title: Message
examples:
- The provided API key is invalid, expired, or revoked.
request_id:
type: string
title: Request Id
examples:
- 8f14e45fceea167a5a36dedd4bea2543
param:
anyOf:
- type: string
- type: 'null'
title: Param
description: Present on validation errors — names the offending field.
examples:
- aspect_ratio
type: object
required:
- type
- code
- message
- request_id
title: ErrorDetail
description: The ``error`` object of the public envelope (ADR §5).
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Organization API key as a bearer token: `Authorization: Bearer
samsa_sk_...`.
````