Skip to main content
POST
Create a model from reference images (URLs and/or base64)
Crée un modèle à partir d’images de référence fournies inline. L’appel renvoie 202 Accepted avec un id de modèle ; interroge GET /models/{id}/status jusqu’à completed. Chacune des 1 à 10 images est soit une url https (téléchargée côté serveur sous protections SSRF) soit du base64 inline + mime_type (image/jpeg, image/png, ou image/webp, ≤ 10 Mo chacune). L’instruction optionnelle est la guidance toujours appliquée du modèle — injectée comme directive obligatoire (“MUST FOLLOW”) dans chaque génération qui compose le modèle, pas une simple note d’usage (modifie-la plus tard avec PATCH /models/{id}). Nécessite le scope models.write.

Exemple : créer un modèle de style à partir d’URLs

Chaque image est soit une url soit du base64 + mime_type, pas les deux. Pour les fichiers volumineux, utilise plutôt le flux presigned upload. category vaut l’une des valeurs style, object, person, setting.

Autorisations

Authorization
string
header
requis

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

Corps

application/json

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

name
string
requis
Required string length: 1 - 100
Exemple:

"Acme Brand Style"

category
enum<string>
requis

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

Options disponibles:
style,
object,
person,
setting
Exemple:

"style"

images
PublicModelImageInput · object[]
requis

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
Exemple:

"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).

Exemple:

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

Réponse

Successful Response

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

id
string<uuid>
requis

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

status
enum<string>
requis

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

Options disponibles:
pending,
processing,
completed,
failed
Exemple:

"pending"

estimated_credits
integer
requis

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

Exemple:

0