Skip to main content
POST
/
models
/
prepare
Request presigned upload URLs for a new model's images
curl --request POST \
  --url https://api.samsa.ai/public/v1/models/prepare \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "files": [
    {
      "filename": "logo.png",
      "content_type": "image/webp",
      "size": 204800
    }
  ],
  "instruction": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "uploads": [
    {
      "key": "<string>",
      "upload_url": "<string>",
      "index": 123
    }
  ],
  "expires_in": 123
}
Step one of the presigned upload flow for large files. Send the model name, category, and metadata for the 1–10 files you will upload (the first file is the cover). The response returns a model id and one presigned PUT upload_url per file. PUT each file to its URL, then call POST /models/{id}/complete with the uploaded keys to start processing. Requires the models.write scope.
Use this two-step flow when images are too large to send inline. For small images or remote URLs, POST /models is simpler. Each file’s content_type is one of image/jpeg, image/png, image/webp; provide size (≤ 10 MB) when you know it.

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/prepare body — request presigned PUT URLs for large files.

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"

files
PublicModelFileMeta · object[]
required

Metadata for the 1-10 files you will upload (first = cover).

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

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

Maximum string length: 8000

Response

Successful Response

202 body for POST /models/prepare — presigned upload slots.

id
string<uuid>
required

The PENDING model's id (send to /complete).

uploads
PublicUploadSlot · object[]
required
expires_in
integer
required

Presigned URL lifetime in seconds.

Example:

3600