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

# Create chat completion

> Generate a response for a text or multimodal conversation, using the OpenAI chat completions request and response format.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/chat/completions
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/chat/completions:
    post:
      tags:
        - Chat Completions
      summary: Create chat completion
      description: >-
        Generate a response for a text or multimodal conversation, using the
        OpenAI chat completions request and response format.
      operationId: handle_chat_completions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
        required: true
      responses:
        '200':
          description: Chat completion generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionStreamResponse'
        '400':
          description: The request was invalid or could not be processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              examples:
                audio_token_limit_exceeded:
                  summary: >-
                    An audio item, or the audio track of a video, exceeds the
                    model's audio limit. Audio is never truncated.
                  value:
                    error:
                      message: >-
                        Audio at messages[0].content[1] is 912.4 s (11405 audio
                        tokens). This model accepts at most 8192 audio tokens
                        per item (about 655 s). Audio is not truncated; shorten
                        or split it.
                      type: invalid_request_error
                      param: messages[0].content[1].input_audio
                      code: audio_token_limit_exceeded
                tool_calling_not_supported:
                  summary: >-
                    The request declares tools, or has tool calls or results in
                    `messages`, and the model does not support tool calling
                  value:
                    error:
                      message: Model 'perceptron-mk1' does not support tool calling
                      type: invalid_request_error
                      param: tools
                      code: unsupported_parameter
                unsupported_input:
                  summary: The model does not support an input in the request
                  value:
                    error:
                      message: Model 'test' does not support video input
                      type: invalid_request_error
                      param: null
                      code: null
        '401':
          description: Authentication failed. Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  message: Invalid API key
                  type: authentication_error
                  param: null
                  code: null
        '429':
          description: >-
            Rate limit exceeded or quota exceeded. Too many requests or
            insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  message: >-
                    Organization rate limit exceeded (300 requests/minute).
                    Please retry after 30 seconds.
                  type: rate_limit_error
                  param: null
                  code: rate_limit_exceeded
        '500':
          description: Internal server error while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  message: The server had an error while processing your request.
                  type: server_error
                  param: null
                  code: null
        '503':
          description: >-
            The model is temporarily overloaded and dropped the request before
            processing it. Retry after the number of seconds in the Retry-After
            header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  message: >-
                    The model is currently overloaded with other requests.
                    Please retry after a short wait.
                  type: server_error
                  param: null
                  code: model_overloaded
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateChatCompletionRequest:
      type: object
      required:
        - messages
        - model
      properties:
        frequency_penalty:
          type:
            - number
            - 'null'
          format: float
          description: >-
            Positive values discourage the model from repeating previously used
            tokens.
          maximum: 2
          minimum: -2
        max_completion_tokens:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Maximum number of completion tokens to generate. Must fit within the
            selected model's context and output limits.
          minimum: 0
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionRequestMessage'
          description: >-
            Conversation history listed in order. Supported roles: `system`,
            `developer` (treated as `system`),

            `user`, `assistant`, `tool`.
        model:
          type: string
          description: >-
            The model to invoke. Use `GET /v1/models` to discover available
            model IDs. New Perceptron requests should use

            `perceptron-mk1.5`.
        'n':
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Number of completions to generate. Only `1` is supported; greater
            values are rejected.
          maximum: 1
          minimum: 1
        parallel_tool_calls:
          type:
            - boolean
            - 'null'
          description: >-
            Whether the model may call several functions in one turn. Defaults
            to `true`. Ignored

            without functions in `tools`.
        presence_penalty:
          type:
            - number
            - 'null'
          format: float
          description: Positive values encourage the model to introduce new concepts.
          maximum: 2
          minimum: -2
        reasoning_effort:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ReasoningEffort'
              description: >-
                How much the model reasons before it answers: `none`, `minimal`,
                `low`, `medium` or `high`.

                A tier other than `none` turns reasoning on.
                `vision_config.enable_thinking`, when set,

                decides whether the model reasons; the tier then only applies
                while reasoning is on.
        regex:
          type:
            - string
            - 'null'
          description: Regex pattern for constrained generation.
        response_format:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ChatCompletionResponseFormat'
              description: >-
                An object specifying the format that the model must output.

                Setting to `{ "type": "json_schema", "json_schema": {...} }`
                enables Structured Outputs

                which ensures the model will match your supplied JSON schema.
        stream:
          type:
            - boolean
            - 'null'
          description: >-
            Set to `true` for SSE streaming. When omitted, the API returns a
            single JSON response.
          default: false
        stream_options:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ChatCompletionStreamOptions'
              description: >-
                Optional streaming flags. Token usage is always reported in the
                final chunk of a streaming response.
        temperature:
          type:
            - number
            - 'null'
          format: float
          description: >-
            Sampling temperature. Lower values yield deterministic replies;
            higher values explore more creative outputs.
          maximum: 2
          minimum: 0
        tool_choice:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ChatCompletionToolChoiceOption'
              description: >-
                Whether the model may call the declared functions: `auto` (the
                default) or `none`. `none` is

                best effort and does not guarantee a response without tool
                calls. Forcing a call (`required`

                or a named function) is not supported and is rejected with a
                400. Ignored without functions

                in `tools`.
        tools:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ChatCompletionTool'
          description: >-
            Functions the model may call and the caller executes. Cannot be
            combined with a

            `json_schema` `response_format` or `regex`.


            Functions require a model that supports tool calling: other models
            reject them, and tool

            calls or results in `messages`, with a 400. Generation stops at the
            first turn that calls

            functions, so a response carries at most one turn of `tool_calls`.
        top_k:
          type:
            - integer
            - 'null'
          format: int32
          description: Top-k sampling. The model samples from the top k most likely tokens.
          minimum: 0
        top_p:
          type:
            - number
            - 'null'
          format: float
          description: >-
            Nucleus sampling probability. The model samples from the smallest
            token set whose cumulative probability exceeds this threshold.
          maximum: 1
          exclusiveMinimum: 0
        vision_config:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/VisionConfig'
              description: >-
                Perceptron vision-model controls (thinking, spatial output
                format,

                video audio). Only supported on Perceptron-owned models.
    CreateChatCompletionResponse:
      type: object
      description: Non-streaming response body when `stream=false`.
      required:
        - id
        - choices
        - created
        - model
        - object
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatChoice'
        created:
          type: integer
          format: int64
          minimum: 0
        id:
          type: string
        model:
          type: string
        object:
          type: string
        usage:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/CompletionUsage'
    CreateChatCompletionStreamResponse:
      type: object
      description: SSE response payload when `stream=true`.
      required:
        - id
        - choices
        - created
        - model
        - object
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatChoiceStream'
        created:
          type: integer
          format: int64
          minimum: 0
        id:
          type: string
        model:
          type: string
        object:
          type: string
        usage:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/CompletionUsage'
    OpenAIErrorResponse:
      type: object
      description: OpenAI-compatible error response format.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/OpenAIErrorDetail'
    ChatCompletionRequestMessage:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestSystemMessage'
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - system
          title: System
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestSystemMessage'
              description: Treated as `system`.
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - developer
          title: Developer
          description: Treated as `system`.
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestUserMessage'
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - user
          title: User
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestAssistantMessage'
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - assistant
          title: Assistant
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestToolMessage'
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - tool
          title: Tool
      description: >-
        Author role of the message: `system`, `developer`, `user`, `assistant`,
        or `tool`.
    ReasoningEffort:
      type: string
      description: >-
        How much the model reasons before it answers; `none` asks for no
        reasoning.
      enum:
        - none
        - minimal
        - low
        - medium
        - high
    ChatCompletionResponseFormat:
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - text
        - type: object
          required:
            - json_schema
            - type
          properties:
            json_schema:
              $ref: '#/components/schemas/ChatCompletionResponseFormatJsonSchema'
            type:
              type: string
              enum:
                - json_schema
    ChatCompletionStreamOptions:
      type: object
      description: Streaming flags accepted by the API.
      properties:
        include_usage:
          type:
            - boolean
            - 'null'
          description: Include token usage metrics with streaming responses.
    ChatCompletionToolChoiceOption:
      oneOf:
        - oneOf:
            - $ref: '#/components/schemas/ToolChoiceMode'
          title: Mode
        - oneOf:
            - $ref: '#/components/schemas/ChatCompletionNamedToolChoice'
          title: Named function
      description: >-
        Whether the model may call the declared tools. Only `auto` and `none`
        are supported.
    ChatCompletionTool:
      oneOf:
        - type: object
          title: Function
          description: A function the caller runs when the model calls it.
          required:
            - function
            - type
          properties:
            function:
              $ref: '#/components/schemas/FunctionObject'
            type:
              type: string
              enum:
                - function
      description: A function the caller runs when the model calls it.
    VisionConfig:
      type: object
      description: >-
        Perceptron vision-model controls. Only honored by Perceptron-owned
        models.
      properties:
        annotation_format:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AnnotationFormat'
              description: >-
                Annotation format the model should emit (`point`, `box`,
                `polygon`, or `clip`).
        enable_audio_in_video:
          type:
            - boolean
            - 'null'
          description: >-
            When true, the audio track of each video in the request is analyzed
            along with its frames.

            Defaults to false. A video without an audio track is processed as
            video only. Audio content

            parts are analyzed regardless of this setting.
        enable_thinking:
          type:
            - boolean
            - 'null'
          description: >-
            Deprecated: use the top-level `reasoning_effort`. When set, this
            flag decides whether the

            model reasons and the tier only applies while reasoning is on.
          deprecated: true
    ChatChoice:
      type: object
      description: Individual completion sampled by the model.
      required:
        - index
        - message
      properties:
        finish_reason:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FinishReason'
        index:
          type: integer
          format: int32
          minimum: 0
        message:
          $ref: '#/components/schemas/ChatCompletionResponseMessage'
    CompletionUsage:
      type: object
      description: Token accounting emitted with every completion.
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      properties:
        completion_tokens:
          type: integer
          format: int32
          minimum: 0
        prompt_tokens:
          type: integer
          format: int32
          minimum: 0
        prompt_tokens_details:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PromptTokensDetails'
              description: Present when the model reports a per-modality breakdown.
        total_tokens:
          type: integer
          format: int32
          minimum: 0
    ChatChoiceStream:
      type: object
      description: Streaming choice emitted per SSE chunk.
      required:
        - index
      properties:
        delta:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ChatCompletionStreamResponseDelta'
        finish_reason:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FinishReason'
        index:
          type: integer
          format: int32
          minimum: 0
    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'
    ChatCompletionRequestSystemMessage:
      type: object
      description: Single chat message within the request payload.
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/ChatCompletionRequestSystemMessageContent'
    ChatCompletionRequestUserMessage:
      type: object
      description: Single chat message within the request payload.
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/ChatCompletionRequestUserMessageContent'
    ChatCompletionRequestAssistantMessage:
      type: object
      description: Single chat message within the request payload.
      properties:
        content:
          oneOf:
            - type: 'null'
            - $ref: >-
                #/components/schemas/ChatCompletionRequestAssistantMessageContent
              description: >-
                The text of the message. May be `null` or omitted when the
                message has `tool_calls`.
        reasoning_content:
          type:
            - string
            - 'null'
          description: >-
            The `reasoning_content` the model returned for this turn. Send it
            back with the turn's

            `tool_calls` so the model sees the reasoning it generated. Ignored
            on requests with neither

            `tools` nor tool calls or results in `messages`.
        tool_calls:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCall'
          description: >-
            The tool calls the model made in this turn. Requires a model that
            supports tool calling.
    ChatCompletionRequestToolMessage:
      type: object
      description: >-
        The result of a tool call, sent back to the model. Requires a model that
        supports tool calling.
      required:
        - tool_call_id
        - content
      properties:
        content:
          $ref: '#/components/schemas/ChatCompletionRequestToolMessageContent'
          description: >-
            The result, as text or as `text`, `image_url` and `image_file_id`
            parts. Images count toward

            the request's media limit and need a model that accepts image input.
        tool_call_id:
          type: string
          description: The `id` of the tool call this message answers.
    ChatCompletionResponseFormatJsonSchema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        schema: {}
        strict:
          type:
            - boolean
            - 'null'
          description: >-
            When true, the model output will strictly adhere to the provided
            schema.
    ToolChoiceMode:
      type: string
      description: A `tool_choice` mode.
      enum:
        - none
        - auto
        - required
    ChatCompletionNamedToolChoice:
      type: object
      description: A `tool_choice` that forces a call to the named function.
      required:
        - type
        - function
      properties:
        function:
          $ref: '#/components/schemas/FunctionName'
        type:
          $ref: '#/components/schemas/ToolType'
    FunctionObject:
      type: object
      description: A function the model may call.
      required:
        - name
      properties:
        description:
          type:
            - string
            - 'null'
          description: >-
            What the function does, which the model uses to choose when and how
            to call it.
        name:
          type: string
        parameters:
          type: object
          description: >-
            The arguments the function accepts, as a JSON Schema object. Kept
            exactly as sent, including

            the order of its properties.
        strict:
          type:
            - boolean
            - 'null'
          description: >-
            Accepted but not enforced: the arguments the model generates are not
            checked against

            `parameters`.
    AnnotationFormat:
      type: string
      description: Annotation format the model should emit alongside text output.
      enum:
        - point
        - box
        - polygon
        - clip
    FinishReason:
      type: string
      enum:
        - stop
        - length
        - tool_calls
        - tool_error
        - tool_limit
        - interrupted
    ChatCompletionResponseMessage:
      type: object
      description: Message object returned in the assistant's response.
      required:
        - content
        - role
      properties:
        content:
          type:
            - string
            - 'null'
          description: >-
            The text of the message, `null` when there is none (for example when
            the model only

            called tools).
        reasoning_content:
          type:
            - string
            - 'null'
        role:
          $ref: '#/components/schemas/Role'
        tool_calls:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCall'
          description: The tool calls the model made.
    PromptTokensDetails:
      type: object
      description: Breakdown of `prompt_tokens` by input modality.
      required:
        - audio_tokens
      properties:
        audio_tokens:
          type: integer
          format: int32
          description: >-
            Prompt tokens produced from audio input: audio content parts and,
            when

            `vision_config.enable_audio_in_video` is set, video soundtracks. `0`
            means no audio was

            analyzed, including when an opted-in video has no usable soundtrack.
          minimum: 0
    ChatCompletionStreamResponseDelta:
      type: object
      description: Delta payload for streaming responses.
      properties:
        content:
          type:
            - string
            - 'null'
        reasoning_content:
          type:
            - string
            - 'null'
        role:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Role'
        tool_calls:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCallChunk'
    ChatCompletionRequestSystemMessageContent:
      oneOf:
        - type: string
          title: Text
        - type: array
          title: Content parts
          items:
            $ref: '#/components/schemas/ChatCompletionRequestSystemMessageContentPart'
      description: >-
        Chat completion message content as either a string or structured content
        array.
    ChatCompletionRequestUserMessageContent:
      oneOf:
        - type: string
          title: Text
        - type: array
          title: Content parts
          items:
            $ref: '#/components/schemas/ChatCompletionRequestUserMessageContentPart'
      description: >-
        Chat completion message content as either a string or structured content
        array.
    ChatCompletionRequestAssistantMessageContent:
      oneOf:
        - type: string
          title: Text
        - type: array
          title: Content parts
          items:
            $ref: >-
              #/components/schemas/ChatCompletionRequestAssistantMessageContentPart
      description: >-
        Chat completion message content as either a string or structured content
        array.
    ChatCompletionMessageToolCall:
      type: object
      description: A tool call the model made.
      required:
        - id
        - type
        - function
      properties:
        function:
          $ref: '#/components/schemas/FunctionCall'
        id:
          type: string
        type:
          $ref: '#/components/schemas/ToolType'
    ChatCompletionRequestToolMessageContent:
      oneOf:
        - type: string
          title: Text
        - type: array
          title: Content parts
          items:
            $ref: '#/components/schemas/ChatCompletionRequestToolMessageContentPart'
      description: Tool result content as either a string or structured content array.
    FunctionName:
      type: object
      description: The name of a function.
      required:
        - name
      properties:
        name:
          type: string
    ToolType:
      type: string
      description: The type of a tool call or a named tool choice. Always `function`.
      enum:
        - function
    Role:
      type: string
      enum:
        - system
        - user
        - assistant
    ChatCompletionMessageToolCallChunk:
      type: object
      description: >-
        A streamed piece of a tool call. The first piece for an `index` carries
        the call's `id`,

        `type` and `function.name`; later pieces carry only
        `function.arguments`, to be appended.
      required:
        - index
      properties:
        function:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FunctionCallStream'
        id:
          type:
            - string
            - 'null'
        index:
          type: integer
          format: int32
          minimum: 0
        type:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ToolType'
    ChatCompletionRequestSystemMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
          title: Text
    ChatCompletionRequestUserMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
          title: Text
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartImage
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - image_url
          title: Image URL
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartVideo
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - video_url
          title: Video URL
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartVideoFrames
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - video_frames
          title: Video frames
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartImageFileId
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - image_file_id
          title: Image file ID
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartVideoFileId
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - video_file_id
          title: Video file ID
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartInputAudio
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - input_audio
          title: Input audio
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartAudio
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - audio_url
          title: Audio URL
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartAudioFileId
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - audio_file_id
          title: Audio file ID
    ChatCompletionRequestAssistantMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
          title: Text
    FunctionCall:
      type: object
      description: A function the model called.
      required:
        - name
        - arguments
      properties:
        arguments:
          type: string
          description: >-
            The arguments as the model generated them, meant to be JSON. They
            are not validated and

            may be cut off when the response hit its token limit.
        name:
          type: string
    ChatCompletionRequestToolMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
          title: Text
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartImage
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - image_url
          title: Image URL
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartImageFileId
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - image_file_id
          title: Image file ID
    FunctionCallStream:
      type: object
      description: >-
        A streamed piece of a function call. Concatenate the `arguments` of
        every piece with the same

        `index`.
      properties:
        arguments:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
    ChatCompletionRequestMessageContentPartText:
      type: object
      description: Text chunk inside a structured message.
      required:
        - text
      properties:
        text:
          type: string
    ChatCompletionRequestMessageContentPartImage:
      type: object
      description: Image content part containing a URL.
      required:
        - image_url
      properties:
        image_url:
          $ref: '#/components/schemas/ImageUrl'
    ChatCompletionRequestMessageContentPartVideo:
      type: object
      description: Video content part containing a URL.
      required:
        - video_url
      properties:
        video_url:
          $ref: '#/components/schemas/VideoUrl'
    ChatCompletionRequestMessageContentPartVideoFrames:
      type: object
      description: >-
        Content part carrying raw video frames the caller has already decoded,
        as an

        alternative to a single `video_url`.
      required:
        - video_frames
      properties:
        video_frames:
          $ref: '#/components/schemas/VideoFrames'
    ChatCompletionRequestMessageContentPartImageFileId:
      type: object
      description: Image content part referencing an uploaded file by id.
      required:
        - image_file_id
      properties:
        image_file_id:
          $ref: '#/components/schemas/ImageFileId'
    ChatCompletionRequestMessageContentPartVideoFileId:
      type: object
      description: Video content part referencing an uploaded file by id.
      required:
        - video_file_id
      properties:
        video_file_id:
          $ref: '#/components/schemas/VideoFileId'
    ChatCompletionRequestMessageContentPartInputAudio:
      type: object
      description: Audio content part carrying inline base64 audio.
      required:
        - input_audio
      properties:
        input_audio:
          $ref: '#/components/schemas/InputAudio'
    ChatCompletionRequestMessageContentPartAudio:
      type: object
      description: Audio content part containing a URL.
      required:
        - audio_url
      properties:
        audio_url:
          $ref: '#/components/schemas/AudioUrl'
    ChatCompletionRequestMessageContentPartAudioFileId:
      type: object
      description: Audio content part referencing an uploaded file by id.
      required:
        - audio_file_id
      properties:
        audio_file_id:
          $ref: '#/components/schemas/AudioFileId'
    ImageUrl:
      type: object
      description: Inline image reference (an HTTP(S) URL or a base64 data URL).
      required:
        - url
      properties:
        url:
          type: string
    VideoUrl:
      type: object
      description: Video asset referenced inside structured content arrays.
      required:
        - url
      properties:
        url:
          type: string
    VideoFrames:
      type: object
      description: An ordered sequence of decoded video frames passed inline.
      required:
        - frames
      properties:
        frames:
          type: array
          items:
            $ref: '#/components/schemas/VideoFrame'
          minItems: 2
    ImageFileId:
      type: object
      description: Reference to an uploaded image file by its id (e.g. `file-abc...`).
      required:
        - file_id
      properties:
        file_id:
          type: string
    VideoFileId:
      type: object
      description: Reference to an uploaded video file by its id (e.g. `file-abc...`).
      required:
        - file_id
      properties:
        file_id:
          type: string
    InputAudio:
      type: object
      description: 'Inline audio: the file bytes as base64 plus their encoding.'
      required:
        - data
        - format
      properties:
        data:
          type: string
          description: Raw audio file bytes, base64 encoded, without a `data:` URI prefix.
        format:
          type: string
          description: 'Encoding of `data`: `wav`, `mp3`, or `flac`.'
          example: wav
    AudioUrl:
      type: object
      description: >-
        Audio file reference (an HTTP(S) URL or a base64 data URL). Supported
        formats are WAV, MP3, and FLAC.
      required:
        - url
      properties:
        url:
          type: string
    AudioFileId:
      type: object
      description: Reference to an uploaded audio file by its id (e.g. `file-abc...`).
      required:
        - file_id
      properties:
        file_id:
          type: string
    VideoFrame:
      type: object
      description: >-
        A single decoded video frame: an image (HTTP(S) URL or base64 data URL)
        plus

        its timestamp within the clip.
      required:
        - image_url
        - timestamp_ms
      properties:
        image_url:
          $ref: '#/components/schemas/ImageUrl'
        timestamp_ms:
          type: integer
          format: int64
          description: >-
            Offset of this frame from the start of the clip, in milliseconds.
            Timestamps must

            be non-negative and non-decreasing across the `frames` array.
          minimum: 0
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your Perceptron API key

````