> ## 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 multilook chat completions

> Run several independent prompts over one shared, prefilled context.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/chat/completions/multilook
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/multilook:
    post:
      tags:
        - Chat Completions
      summary: Create multilook chat completions
      description: Run several independent prompts over one shared, prefilled context.
      operationId: handle_multilook_completions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMultilookRequest'
        required: true
      responses:
        '200':
          description: >-
            Multilook completions generated successfully. Returns a grouped
            response with one result per prompt; a prompt-level failure appears
            as an `error` entry in place of that prompt's completions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultilookResponse'
        '400':
          description: The request was invalid or could not be processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  message: 'Invalid n: 12. Expected a value between 1 and 8.'
                  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 (150 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
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateMultilookRequest:
      type: object
      description: Request body for `/v1/chat/completions/multilook`.
      required:
        - model
        - context
        - prompts
      properties:
        context:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionRequestMessage'
          description: >-
            Shared prefix all prompts extend — same message format as
            `/v1/chat/completions`, except that

            tool calling is not supported: `tool` messages and assistant
            `tool_calls` are rejected with a

            400. Prefilled once and reused across all prompts within this
            request.
        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 completion tokens, per completion. Must fit within the
            selected model's

            output limit.
          minimum: 0
        model:
          type: string
          description: The model to invoke.
        'n':
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Sampled completions ("looks") per prompt (1 to 8). `n > 1` requires
            `temperature > 0`.
          default: 1
          maximum: 8
          minimum: 1
        presence_penalty:
          type:
            - number
            - 'null'
          format: float
          description: Positive values encourage the model to introduce new concepts.
          maximum: 2
          minimum: -2
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/MultilookPromptInput'
          description: >-
            Independent sequences extending the shared prefix (1 to 16 entries).
            Prompts are

            isolated from one another and never see each other's text or
            completions.
          maxItems: 16
          minItems: 1
        reasoning_effort:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ReasoningEffort'
              description: >-
                How much the model reasons before it answers: `none`, `minimal`,
                `low`, `medium` or `high`.

                One tier for the whole request, applied to every prompt. 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.
        temperature:
          type:
            - number
            - 'null'
          format: float
          description: Sampling temperature, shared across all prompts.
          maximum: 2
          minimum: 0
        top_k:
          type:
            - integer
            - 'null'
          format: int32
          description: Top-k sampling.
          minimum: 0
        top_p:
          type:
            - number
            - 'null'
          format: float
          description: Nucleus sampling probability.
          maximum: 1
          exclusiveMinimum: 0
        vision_config:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/VisionConfig'
              description: Perceptron vision-model controls, shared across all prompts.
    MultilookResponse:
      type: object
      description: Response body for `/v1/chat/completions/multilook`.
      required:
        - id
        - object
        - model
        - results
      properties:
        id:
          type: string
        model:
          type: string
        object:
          type: string
          description: Always `chat.completion.multilook`.
        results:
          type: array
          items:
            $ref: '#/components/schemas/MultilookResult'
          description: One entry per prompt, in request order.
        usage:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MultilookUsage'
    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`.
    MultilookPromptInput:
      oneOf:
        - type: string
          title: Text prompt
        - oneOf:
            - $ref: '#/components/schemas/MultilookStructuredPrompt'
          title: Structured prompt
      description: >-
        One prompt: the content of an implicit final `user` turn extending the
        shared

        `context`. Either a bare string or a structured object carrying content
        parts

        (the same part types as `/v1/chat/completions` user messages, including
        media).
    ReasoningEffort:
      type: string
      description: >-
        How much the model reasons before it answers; `none` asks for no
        reasoning.
      enum:
        - none
        - minimal
        - low
        - medium
        - high
    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
    MultilookResult:
      type: object
      description: >-
        Result for one prompt, in request order: either `completions` (+
        `usage`) or `error`.
      required:
        - prompt_index
      properties:
        completions:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/MultilookCompletion'
        error:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MultilookPromptError'
        prompt_index:
          type: integer
          format: int32
          minimum: 0
        usage:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MultilookPromptUsage'
    MultilookUsage:
      type: object
      description: >-
        Call-level usage. `prompt_tokens` counts the shared context once per
        prompt (same

        meaning as on `/v1/chat/completions`); `total_tokens = prompt_tokens +
        completion_tokens`.
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
        - prompt_tokens_details
      properties:
        completion_tokens:
          type: integer
          format: int32
          minimum: 0
        prompt_tokens:
          type: integer
          format: int32
          minimum: 0
        prompt_tokens_details:
          $ref: '#/components/schemas/MultilookPromptTokensDetails'
        total_tokens:
          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.
    MultilookStructuredPrompt:
      type: object
      description: >-
        Structured prompt content: the same content-part types as
        `/v1/chat/completions` user messages.
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionRequestUserMessageContentPart'
    AnnotationFormat:
      type: string
      description: Annotation format the model should emit alongside text output.
      enum:
        - point
        - box
        - polygon
        - clip
    MultilookCompletion:
      type: object
      description: One sampled completion for a prompt.
      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'
    MultilookPromptError:
      type: object
      description: >-
        Error for a single prompt (e.g. a content guard); the other prompts'
        results

        are unaffected.
      required:
        - message
      properties:
        code:
          type:
            - string
            - 'null'
        message:
          type: string
        type:
          type:
            - string
            - 'null'
    MultilookPromptUsage:
      type: object
      description: >-
        Per-prompt usage. Completion tokens only; prompt tokens are reported
        once in the

        call-level `usage` and never attributed to individual prompts.
      required:
        - completion_tokens
      properties:
        completion_tokens:
          type: integer
          format: int32
          description: Summed across this prompt's `n` completions.
          minimum: 0
    MultilookPromptTokensDetails:
      type: object
      description: Breakdown of `prompt_tokens`, nested inside `usage`.
      required:
        - cached_tokens
        - audio_tokens
      properties:
        audio_tokens:
          type: integer
          format: int32
          description: >-
            Prompt tokens produced from audio input across every prompt: audio
            content parts and,

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

            was analyzed.
          minimum: 0
        cached_tokens:
          type: integer
          format: int32
          description: >-
            Subset of `prompt_tokens` served from the in-request prefill rather
            than

            recomputed. Reuse is scoped to this request: a second identical call
            reports 0.
          minimum: 0
    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.
    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
    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.
    ChatCompletionRequestSystemMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
          title: Text
    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
    ToolType:
      type: string
      description: The type of a tool call or a named tool choice. Always `function`.
      enum:
        - function
    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
    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'
    Role:
      type: string
      enum:
        - system
        - user
        - assistant
    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

````