> ## 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.

# Prepara l'upload di un modello

> Richiedi presigned PUT URL per le immagini di riferimento di un nuovo modello (upload in due passaggi).

Passo uno del flusso di upload con presigned URL per file di grandi dimensioni. Invia il `name` del modello,
la `category` e i metadati per gli 1–10 `files` che caricherai (il **primo** file è
la copertina). La risposta restituisce un `id` del modello e un presigned PUT `upload_url` per
file. Esegui `PUT` di ogni file al suo URL, quindi chiama
[`POST /models/{id}/complete`](/it/api-reference/model-training/complete) con le
chiavi caricate per avviare l'elaborazione. Richiede lo scope `models.write`.

<Note>
  Usa questo flusso in due passaggi quando le immagini sono troppo grandi per essere inviate inline. Per immagini piccole
  o URL remoti, [`POST /models`](/it/api-reference/model-training/create) è più semplice.
  Il `content_type` di ogni file è uno tra `image/jpeg`, `image/png`, `image/webp`;
  fornisci `size` (≤ 10 MB) quando lo conosci.
</Note>


## OpenAPI

````yaml api-reference/openapi.json POST /models/prepare
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/prepare:
    post:
      tags:
        - Models
      summary: Request presigned upload URLs for a new model's images
      description: >-
        Two-step upload for large files: `prepare` returns presigned PUT URLs
        (one per file, first = cover), you PUT each file, then call `POST
        /models/{id}/complete`. Requires the `models.write` scope.
      operationId: prepare_model_models_prepare_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicModelPrepareRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicModelPrepareResponse'
        '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 user's private model, another
            organization, a Samsa default/library model, deleted, or not
            public). Your own models — including your private ones — and
            non-private models in your organization are accessible.
          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:
    PublicModelPrepareRequest:
      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
        files:
          items:
            $ref: '#/components/schemas/PublicModelFileMeta'
          type: array
          maxItems: 10
          minItems: 1
          title: Files
          description: Metadata for the 1-10 files you will upload (first = cover).
        instruction:
          anyOf:
            - type: string
              maxLength: 8000
            - type: 'null'
          title: Instruction
          description: Optional free-text guidance for how to use the model.
      type: object
      required:
        - name
        - category
        - files
      title: PublicModelPrepareRequest
      description: >-
        `POST /models/prepare` body — request presigned PUT URLs for large
        files.
    PublicModelPrepareResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: The PENDING model's id (send to `/complete`).
        uploads:
          items:
            $ref: '#/components/schemas/PublicUploadSlot'
          type: array
          title: Uploads
        expires_in:
          type: integer
          title: Expires In
          description: Presigned URL lifetime in seconds.
          examples:
            - 3600
      type: object
      required:
        - id
        - uploads
        - expires_in
      title: PublicModelPrepareResponse
      description: '`202` body for `POST /models/prepare` — presigned upload slots.'
    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.
    PublicModelFileMeta:
      properties:
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Original filename (informational).
          examples:
            - logo.png
        content_type:
          type: string
          title: Content Type
          description: >-
            MIME type of the file to upload — one of: image/jpeg, image/png,
            image/webp.
          default: image/webp
          examples:
            - image/png
        size:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Size
          description: File size in bytes (optional; must be ≤ 10 MB when provided).
          examples:
            - 204800
      type: object
      title: PublicModelFileMeta
      description: One presigned-upload slot request (`POST /models/prepare`).
    PublicUploadSlot:
      properties:
        key:
          type: string
          title: Key
          description: R2 object key to send back in `uploaded_keys`.
        upload_url:
          type: string
          title: Upload Url
          description: Presigned PUT URL (expires with `expires_in`).
        index:
          type: integer
          title: Index
          description: Slot index (0 = primary/cover).
      type: object
      required:
        - key
        - upload_url
        - index
      title: PublicUploadSlot
      description: A presigned PUT slot returned by `POST /models/prepare`.
    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_...`.

````