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

# List Models

> Returns a list of models available in the API. Use the `extended` query parameter
to get additional metadata about each model's capabilities and supported features.

## Overview

The Models API returns a list of models available in the Perceptron API. This endpoint is compatible with OpenAI's model listing specification.

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

## Examples

### List Available Models

Retrieve a basic list of all available models:

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

### Get Extended Model Metadata

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

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

## Rate Limits

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

## Use Cases

* **Model Discovery**: Query available models before making inference requests
* **Capability Checking**: Verify a model supports specific features (structured outputs, video input, etc.)
* **Dynamic Configuration**: Build UIs that adapt to model capabilities
* **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
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:
    get:
      tags:
        - Models
      summary: List available models
      description: >-
        Returns a list of models available in the API. Use the `extended` query
        parameter

        to get additional metadata about each model's capabilities and supported
        features.
      operationId: handle_get_models
      parameters:
        - name: extended
          in: query
          description: >-
            If true, returns extended model metadata including capabilities,
            modalities, and limits.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: >-
            List of available models. Returns `GetModelsResponse` when
            `extended=false` (default), or `GetModelsExtendedResponse` when
            `extended=true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelsResponseUnion'
        '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
        '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:
    GetModelsResponseUnion:
      oneOf:
        - $ref: '#/components/schemas/GetModelsResponse'
        - $ref: '#/components/schemas/GetModelsExtendedResponse'
      description: >-
        Response union for GET /v1/models endpoint.

        Returns GetModelsResponse when extended=false (default), or
        GetModelsExtendedResponse when extended=true.
    OpenAIErrorResponse:
      type: object
      description: OpenAI-compatible error response format.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/OpenAIErrorDetail'
    GetModelsResponse:
      type: object
      description: OpenAI-compatible response for GET /v1/models
      required:
        - object
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
          description: List of available models.
        object:
          type: string
          description: Object type, always "list".
    GetModelsExtendedResponse:
      type: object
      description: Extended response for GET /v1/models?extended=true
      required:
        - object
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ModelExtended'
          description: List of available models with extended metadata.
        object:
          type: string
          description: Object type, always "list".
    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'
    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
    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

````