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

# Ottieni un modello

> Recupera il dettaglio completo di uno dei modelli della tua organizzazione.

Restituisce il dettaglio completo di un singolo modello di proprietà della tua organizzazione, incluse le
presigned URL delle immagini di riferimento, il prompt predefinito, le trigger word e lo `user_instruction`
del modello. Questo `user_instruction` è la **guida sempre applicata** del modello: viene iniettato come
direttiva obbligatoria ("MUST FOLLOW") in ogni generazione di immagini e video che compone il modello — non
sono metadati passivi. Si distingue dal `default_prompt`, una descrizione delle capacità generata dall'IA che
viene anch'essa aggiunta alla generazione. Impostalo o modificalo tramite
[`PATCH /models/{model_id}`](/it/api-reference/models/update). Gli id sconosciuti, di un'altra organizzazione o
eliminati restituiscono
[`404 not_found`](/it/guides/errors#not_found). Richiede lo scope `models.read`.


## OpenAPI

````yaml api-reference/openapi.json GET /models/{model_id}
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/{model_id}:
    get:
      tags:
        - Models
      summary: Retrieve one of your models
      description: >-
        Returns full detail for a single model you can access — one you own
        (including your own `private` models) or a non-private model shared
        within your organization — including presigned reference-image URLs, the
        user instruction, the default prompt, and trigger words. Another user's
        private model, another organization's model, a Samsa default/library
        model, or a deleted / internal model returns `404`. Requires the
        `models.read` scope.
      operationId: get_model_models__model_id__get
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Model Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicModelDetail'
        '401':
          description: Missing, invalid, expired, or revoked API key.
          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'
components:
  schemas:
    PublicModelDetail:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
          examples:
            - Acme Brand Style
        category:
          anyOf:
            - $ref: '#/components/schemas/PublicModelCategory'
            - type: 'null'
          description: Model category — one of `style`, `object`, `person`, `setting`.
          examples:
            - style
        status:
          $ref: '#/components/schemas/PublicModelStatus'
          description: 'Creation status: `pending`, `processing`, `completed`, or `failed`.'
          examples:
            - completed
        is_ready:
          type: boolean
          title: Is Ready
          description: >-
            True when the model is `completed` AND active — usable for
            generation.
          examples:
            - true
        thumbnail_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Thumbnail Url
          description: >-
            Presigned, time-limited HTTPS thumbnail URL (null when the model has
            none).
          examples:
            - https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        reference_image_urls:
          items:
            type: string
          type: array
          title: Reference Image Urls
          description: >-
            Presigned, time-limited HTTPS URLs of the reference images used to
            create the model.
          examples:
            - - https://cdn.samsa.ai/models/…/ref-0.webp?X-Amz-Signature=…
        user_instruction:
          anyOf:
            - type: string
            - type: 'null'
          title: User Instruction
          description: Free-text guidance for how to use the model.
          examples:
            - Use for hero banners and social posts.
        default_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Default Prompt
          description: The model's default prompt / capability description.
          examples:
            - A bold flat-design illustration in the Acme brand palette.
        trigger_words:
          items:
            type: string
          type: array
          title: Trigger Words
          description: Trigger words associated with the model.
          examples:
            - - acme
      type: object
      required:
        - id
        - name
        - status
        - is_ready
        - created_at
        - updated_at
      title: PublicModelDetail
      description: >-
        A single model with full detail — the ``GET /models/{id}`` body (ADR
        §10).
    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.
    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_...`.

````