Skip to main content
POST
Create a model from reference images (URLs and/or base64)
Crea un modello a partire da immagini di riferimento fornite inline. La chiamata restituisce 202 Accepted con un id del modello; interroga GET /models/{id}/status finché non è completed. Ciascuna delle 1–10 images è o un url https (scaricato lato server con protezioni SSRF) oppure base64 inline + mime_type (image/jpeg, image/png o image/webp, ≤ 10 MB ciascuna). L’instruction facoltativa è la guida sempre applicata del modello — iniettata come direttiva obbligatoria (“MUST FOLLOW”) in ogni generazione che compone il modello, non una semplice nota d’uso (modificala in seguito con PATCH /models/{id}). Richiede lo scope models.write.

Esempio: crea un modello di stile da URL

Ogni immagine è o un url oppure base64 + mime_type, non entrambi. Per file di grandi dimensioni, usa invece il flusso di upload con presigned URL. category è uno tra style, object, person, setting.

Autorizzazioni

Authorization
string
header
obbligatorio

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

Corpo

application/json

POST /models body — inline base64 and/or https-URL reference images.

name
string
obbligatorio
Required string length: 1 - 100
Esempio:

"Acme Brand Style"

category
enum<string>
obbligatorio

Model category — one of style, object, person, setting.

Opzioni disponibili:
style,
object,
person,
setting
Esempio:

"style"

images
PublicModelImageInput · object[]
obbligatorio

1-10 reference images, each a url or inline base64+mime_type.

Required array length: 1 - 10 elements
instruction
string | null

Optional free-text guidance for how to use the model.

Maximum string length: 8000
Esempio:

"Use for hero banners and social posts."

webhook_url
string | null

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

Esempio:

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

Risposta

Successful Response

202 body for POST /models and POST /models/{id}/complete (ADR §7.1).

id
string<uuid>
obbligatorio

The created model's id — poll GET /models/{id}/status.

status
enum<string>
obbligatorio

Initial status: pending (create) or processing (complete).

Opzioni disponibili:
pending,
processing,
completed,
failed
Esempio:

"pending"

estimated_credits
integer
obbligatorio

Credits the finished job will cost (model creation is free = 0).

Esempio:

0