> ## 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.
# Create a model
> Create a model from 1–10 reference images supplied as URLs or inline base64.
Create a model from reference images supplied inline. The call returns
**`202 Accepted`** with a model `id`; poll
[`GET /models/{id}/status`](/api-reference/model-training/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
```bash curl theme={null}
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"
}'
```
```json Body theme={null}
{
"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](/api-reference/model-training/prepare)
instead. `category` is one of `style`, `object`, `person`, `setting`.
## OpenAPI
````yaml api-reference/openapi.json POST /models
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:
/models:
post:
tags:
- Models
summary: Create a model from reference images (URLs and/or base64)
description: >-
Creates a new model from 1-10 reference images — each an `https` `url`
(downloaded server-side under SSRF guards) or inline
`base64`+`mime_type` (jpeg/png/webp, ≤ 10 MB each). Returns `202`
immediately; poll `GET /models/{id}/status`. Requires the `models.write`
scope.
operationId: create_model_models_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/PublicModelCreateRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicModelCreateAccepted'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'402':
description: The organization has no usable subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: The API key lacks the required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: >-
Model not found (unknown id, another organization, deleted, or not
public).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Request validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Model creation is disabled on this deployment.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
PublicModelCreateRequest:
properties:
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Acme Brand Style
category:
$ref: '#/components/schemas/PublicModelCategory'
description: Model category — one of `style`, `object`, `person`, `setting`.
examples:
- style
images:
items:
$ref: '#/components/schemas/PublicModelImageInput'
type: array
maxItems: 10
minItems: 1
title: Images
description: 1-10 reference images, each a `url` or inline `base64`+`mime_type`.
instruction:
anyOf:
- type: string
maxLength: 8000
- type: 'null'
title: Instruction
description: Optional free-text guidance for how to use the model.
examples:
- Use for hero banners and social posts.
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:
- name
- category
- images
title: PublicModelCreateRequest
description: '`POST /models` body — inline base64 and/or https-URL reference images.'
PublicModelCreateAccepted:
properties:
id:
type: string
format: uuid
title: Id
description: The created model's id — poll `GET /models/{id}/status`.
status:
$ref: '#/components/schemas/PublicModelStatus'
description: 'Initial status: `pending` (create) or `processing` (complete).'
examples:
- pending
estimated_credits:
type: integer
title: Estimated Credits
description: Credits the finished job will cost (model creation is free = 0).
examples:
- 0
type: object
required:
- id
- status
- estimated_credits
title: PublicModelCreateAccepted
description: >-
`202` body for `POST /models` and `POST /models/{id}/complete` (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).
PublicModelCategory:
type: string
enum:
- style
- object
- person
- setting
title: PublicModelCategory
description: >-
Public model category (ADR §8.2).
Maps to the internal ``ModelType`` stored in ``models.type`` (NOT the
separate
``models.category`` column). ``setting`` is the public name for internal
``SCENE``; the others are a straight upper/lower-case swap. Internal
``BASE`` is
never exposed publicly.
PublicModelImageInput:
properties:
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: https URL of the reference image (downloaded under SSRF guards).
examples:
- https://cdn.example.com/ref-0.png
base64:
anyOf:
- type: string
- type: 'null'
title: Base64
description: Base64-encoded image bytes (send with `mime_type`).
mime_type:
anyOf:
- type: string
- type: 'null'
title: Mime Type
description: >-
MIME type for a base64 image — one of: image/jpeg, image/png,
image/webp.
examples:
- image/png
type: object
title: PublicModelImageInput
description: >-
One reference image — either an ``https`` ``url`` to download OR inline
base64.
Exactly one mode: ``url`` (server-side SSRF-guarded download) XOR
(``base64`` + ``mime_type``). Base64 ``mime_type`` must be in the public
allow-list; decoded-size validation happens in the route (§1) so we do
not
base64-decode inside the schema.
PublicModelStatus:
type: string
enum:
- pending
- processing
- completed
- failed
title: PublicModelStatus
description: >-
Public model creation / readiness status — the lower-cased internal
status.
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_...`.
````