Skip to main content
POST
Create a model from reference images (URLs and/or base64)
Erstelle ein Modell aus inline übergebenen Referenzbildern. Der Aufruf gibt 202 Accepted mit einer Modell-id zurück; frage GET /models/{id}/status ab, bis completed. Jedes der 1–10 images ist entweder eine https url (serverseitig heruntergeladen unter SSRF-Schutz) oder inline base64 + mime_type (image/jpeg, image/png oder image/webp, je ≤ 10 MB). Die optionale instruction ist die stets angewandte Guidance des Modells — als verbindliche (“MUST FOLLOW”) Vorgabe in jede Generierung eingespeist, die das Modell komponiert, kein passiver Nutzungshinweis (ändere sie später mit PATCH /models/{id}). Erfordert den models.write Scope.

Beispiel: ein Style-Modell aus URLs erstellen

Jedes Bild ist entweder eine url oder base64 + mime_type, nicht beides. Für große Dateien nutze stattdessen den Presigned-Upload-Flow. category ist eine von style, object, person, setting.

Autorisierungen

Authorization
string
header
erforderlich

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

Body

application/json

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

name
string
erforderlich
Required string length: 1 - 100
Beispiel:

"Acme Brand Style"

category
enum<string>
erforderlich

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

Verfügbare Optionen:
style,
object,
person,
setting
Beispiel:

"style"

images
PublicModelImageInput · object[]
erforderlich

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

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

Beispiel:

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

Antwort

Successful Response

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

id
string<uuid>
erforderlich

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

status
enum<string>
erforderlich

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

Verfügbare Optionen:
pending,
processing,
completed,
failed
Beispiel:

"pending"

estimated_credits
integer
erforderlich

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

Beispiel:

0