Skip to main content
POST
/
models
Create a model from reference images (URLs and/or base64)
curl --request POST \
  --url https://api.samsa.ai/public/v1/models \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "images": [
    {
      "url": "https://cdn.example.com/ref-0.png",
      "base64": "<string>",
      "mime_type": "image/png"
    }
  ],
  "instruction": "Use for hero banners and social posts.",
  "webhook_url": "https://example.com/webhooks/samsa"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}
Create a model from reference images supplied inline. The call returns 202 Accepted with a model id; poll GET /models/{id}/status until completed. Each of the 1–10 images is either an https url (downloaded server-side under SSRF guards) or inline base64 + mime_type (image/jpeg, image/png, or image/webp, ≤ 10 MB each). Requires the models.write scope.

​
Example: create a style model from URLs

curl -X POST https://api.samsa.ai/public/v1/models \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Brand Style",
    "category": "style",
    "images": [
      { "url": "https://cdn.example.com/ref-0.png" },
      { "url": "https://cdn.example.com/ref-1.png" },
      { "url": "https://cdn.example.com/ref-2.png" }
    ],
    "instruction": "Use for hero banners and social posts.",
    "webhook_url": "https://api.example.com/hooks/samsa"
  }'
Each image is either a url or base64 + mime_type, not both. For large files, use the presigned upload flow instead. category is one of style, object, person, setting.

Authorizations

​
Authorization
string
header
required

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

Headers

​
authorization
string | null

Body

application/json

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

​
name
string
required
Required string length: 1 - 100
Example:

"Acme Brand Style"

​
category
enum<string>
required

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

Available options:
style,
object,
person,
setting
Example:

"style"

​
images
PublicModelImageInput · object[]
required

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

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

Example:

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

Response

Successful Response

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

​
id
string<uuid>
required

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

​
status
enum<string>
required

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

Available options:
pending,
processing,
completed,
failed
Example:

"pending"

​
estimated_credits
integer
required

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

Example:

0