> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Model

> Returns a specific model by its ID. Use the `extended` query parameter
to get additional metadata about the model's capabilities and supported features.

## Overview

The Retrieve Model API returns a specific model by its ID. This endpoint is compatible with OpenAI's model retrieval specification.

Use the optional `extended` query parameter to retrieve detailed metadata about the model, including capabilities, supported input/output modalities, and token limits.

## Examples

### Retrieve a Model

Get basic information about a specific model:

```bash theme={null}
curl --location 'https://api.perceptron.inc/v1/models/perc-x1' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

### Get Extended Model Metadata

Retrieve detailed information about a model's capabilities and limits:

```bash theme={null}
curl --location 'https://api.perceptron.inc/v1/models/perc-x1?extended=true' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

## Rate Limits

This endpoint is limited to **30 requests/min**.

## Use Cases

* **Model Validation**: Verify a specific model exists and is available before making inference requests
* **Capability Checking**: Check if a model supports specific features (structured outputs, video input, etc.)
* **Dynamic Configuration**: Fetch model details to adapt UI or request parameters
* **Token Limit Validation**: Check context and output limits before sending requests

See the API reference below for complete request/response schemas.


## OpenAPI

````yaml api-reference/openapi.json GET /v1/models/{model_id}
openapi: 3.1.0
info:
  title: Perceptron API
  contact:
    name: Perceptron API Support
    email: support@perceptron.inc
  version: 1.0.0
servers:
  - url: https://api.perceptron.inc
security: []
tags:
  - name: Chat Completions
    description: Chat completions API (OpenAI-compatible)
  - name: Detection
    description: Native Perceptron image detection API
  - name: Models
    description: Model listing and metadata API
  - name: Files
    description: File upload, listing, retrieval, and deletion API
paths:
  /v1/models/{model_id}:
    get:
      tags:
        - Models
      summary: Retrieve a model
      description: >-
        Returns a specific model by its ID. Use the `extended` query parameter

        to get additional metadata about the model's capabilities and supported
        features.
      operationId: handle_get_model
      parameters:
        - name: model_id
          in: path
          description: The ID of the model to retrieve.
          required: true
          schema:
            type: string
        - name: extended
          in: query
          description: >-
            If true, returns extended model metadata including capabilities,
            modalities, and limits.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: >-
            The model with the given ID. Returns `Model` when `extended=false`
            (default), or `ModelExtended` when `extended=true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelResponseUnion'
        '401':
          description: Authentication failed. Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  code: null
                  message: Invalid API key
                  param: null
                  type: authentication_error
        '404':
          description: Model not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  code: model_not_found
                  message: The model 'unknown-model' does not exist
                  param: model
                  type: invalid_request_error
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Organization rate limit exceeded (30 requests/minute).
                    Please retry after 30 seconds.
                  param: null
                  type: rate_limit_error
        '500':
          description: Internal server error while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  code: null
                  message: The server had an error while processing your request.
                  param: null
                  type: server_error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    GetModelResponseUnion:
      oneOf:
        - $ref: '#/components/schemas/Model'
        - $ref: '#/components/schemas/ModelExtended'
      description: >-
        Response union for GET /v1/models/{model_id} endpoint.

        Returns Model when extended=false (default), or ModelExtended when
        extended=true.
    OpenAIErrorResponse:
      type: object
      description: OpenAI-compatible error response format.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/OpenAIErrorDetail'
    Model:
      type: object
      description: OpenAI-compatible model object (base fields)
      required:
        - id
        - object
        - created
        - owned_by
      properties:
        created:
          type: integer
          format: int64
          description: Unix timestamp when the model was created.
        id:
          type: string
          description: The model identifier.
        object:
          type: string
          description: Object type, always "model".
        owned_by:
          $ref: '#/components/schemas/Owner'
          description: The organization that owns the model.
    ModelExtended:
      allOf:
        - $ref: '#/components/schemas/Model'
          description: Base model fields (id, object, created, owned_by).
        - type: object
          required:
            - name
            - capabilities
            - modalities
            - output_formats
            - internal_tools
            - sampling_parameters
            - reasoning
            - max_context_tokens
            - max_output_tokens
            - credits_per_million_input_tokens
            - credits_per_million_output_tokens
            - early_access
          properties:
            capabilities:
              type: array
              items:
                $ref: '#/components/schemas/Capability'
              description: List of special capabilities supported by this model.
            credits_per_million_input_tokens:
              type: integer
              format: int64
              description: Cost in credits per million input tokens.
              minimum: 0
            credits_per_million_output_tokens:
              type: integer
              format: int64
              description: Cost in credits per million output tokens.
              minimum: 0
            description:
              type:
                - string
                - 'null'
              description: Optional description of the model.
            early_access:
              type: boolean
              description: Whether this model is in early access (preview).
            internal_tools:
              type: array
              items:
                $ref: '#/components/schemas/InternalTool'
              description: List of internal tools available to this model.
            max_context_tokens:
              type: integer
              format: int64
              description: Maximum number of tokens in the context window.
              minimum: 0
            max_output_tokens:
              type: integer
              format: int64
              description: Maximum number of tokens the model can output.
              minimum: 0
            modalities:
              type: array
              items:
                $ref: '#/components/schemas/Modality'
              description: List of modalities this model accepts.
            name:
              type: string
              description: Human-readable display name for the model.
            output_formats:
              type: array
              items:
                $ref: '#/components/schemas/OutputFormat'
              description: List of output formats this model can produce.
            reasoning:
              $ref: '#/components/schemas/Reasoning'
              description: Reasoning capability configuration.
            sampling_parameters:
              type: array
              items:
                $ref: '#/components/schemas/SamplingParameter'
              description: List of sampling parameters this model supports.
      description: Extended model with OpenAI base fields flattened
    OpenAIErrorDetail:
      type: object
      description: OpenAI-compatible error detail.
      required:
        - message
      properties:
        code:
          type:
            - string
            - 'null'
        message:
          type: string
        param:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
    Owner:
      type: string
      description: Owner of a model.
      enum:
        - perceptron
    Capability:
      type: string
      description: Special capabilities that a model may support.
      enum:
        - response_format_json_schema
        - regex
    InternalTool:
      type: string
      description: Internal tools available to the model.
      enum:
        - zoom
    Modality:
      type: string
      description: Types of modalities the model can accept.
      enum:
        - image
        - video
    OutputFormat:
      type: string
      description: Types of output formats the model can produce.
      enum:
        - text
        - point
        - box
        - polygon
        - clip
    Reasoning:
      type: object
      description: Reasoning capability configuration for a model.
      required:
        - supported
        - always_enabled
      properties:
        always_enabled:
          type: boolean
          description: Whether reasoning is always enabled for this model.
        supported:
          type: boolean
          description: Whether the model supports reasoning mode.
    SamplingParameter:
      type: string
      description: Sampling parameters the model supports for generation.
      enum:
        - temperature
        - top_p
        - top_k
        - frequency_penalty
        - presence_penalty
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your Perceptron API key

````