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

# Multilook Chat Completions

## Overview

A multilook request carries a shared `context` — the same message format as `/v1/chat/completions`, including media parts (`image_url`, `video_url`, `video_frames`, `image_file_id`, `video_file_id`) — and up to 16 `prompts`. The context is prefilled once per call and reused across all prompts; each prompt extends it independently and produces `n` completions. Prompts are isolated from one another: no prompt observes another prompt's text or completions.

Reused prefill is reported in `usage.prompt_tokens_details.cached_tokens` and billed at the cache-read rate. The [Multilook guide](/perceptron-mk1/guides/multilook) covers when to use it, how billing works, and Python client code.

## Request

```bash theme={null}
curl https://api.perceptron.inc/v1/chat/completions/multilook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "perceptron-mk1",
    "context": [
      { "role": "user",
        "content": [
          { "type": "video_url",
            "video_url": { "url": "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/main/cookbook/_shared/assets/tutorials/isaac_frame_by_frame/surf.mp4" }
          }
        ]
      }
    ],
    "prompts": [
      "How many people are visible?",
      "Describe the setting in one sentence.",
      "Does anyone pick up an object? If so, what?"
    ],
    "n": 1,
    "max_completion_tokens": 128
  }'
```

| Field                                                                    | Description                                                                                                                                                                                                    |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                                                                  | The model to invoke.                                                                                                                                                                                           |
| `context`                                                                | Shared prefix all prompts extend — same message format as `/v1/chat/completions`, including media parts (`image_url`, `video_url`, `video_frames`, file ids). Prefilled once per call.                         |
| `prompts`                                                                | 1–16 independent sequences extending the shared prefix. Each entry is the content of an implicit final `user` turn: a bare string, or `{ "content": [ ...parts ] }` with the same part types as user messages. |
| `n`                                                                      | Completions per prompt, 1–8. `n > 1` requires `temperature > 0`.                                                                                                                                               |
| `max_completion_tokens`                                                  | Maximum completion tokens, per completion (up to 8192).                                                                                                                                                        |
| `temperature`, `top_p`, `top_k`, `frequency_penalty`, `presence_penalty` | Sampling parameters, applied to all prompts.                                                                                                                                                                   |
| `vision_config`                                                          | Perceptron vision-model controls (e.g. `enable_thinking`), applied to all prompts.                                                                                                                             |

`temperature` defaults to `0.0`, so set it explicitly whenever `n > 1`.

`stream`, `response_format`, and `stop` are not supported on this endpoint.

### Structured prompts

A prompt can be a bare string or an object carrying content parts, so individual prompts can bring their own media alongside the shared context:

```json theme={null}
"prompts": [
  "Describe the setting in one sentence.",
  { "content": [
      { "type": "image_url", "image_url": { "url": "<image-url>" } },
      { "type": "text", "text": "Does this still frame match the video?" }
    ]
  }
]
```

Media parts inside a `prompts` entry sit outside the shared prefix: they are fetched, preprocessed, and prefilled per prompt, and are not reported in `cached_tokens`. Media intended for reuse across prompts belongs in `context`. See [Per-prompt media](/perceptron-mk1/guides/multilook#per-prompt-media) in the guide for a full example.

## Response

One entry per prompt, in request order:

```json theme={null}
{
  "id": "mlcmpl-2b9e41",
  "object": "chat.completion.multilook",
  "model": "perceptron-mk1",
  "results": [
    { "prompt_index": 0,
      "completions": [
        { "index": 0,
          "message": { "role": "assistant", "content": "Two people are visible." },
          "finish_reason": "stop" }
      ],
      "usage": { "completion_tokens": 6 } },
    { "prompt_index": 1,
      "completions": [
        { "index": 0,
          "message": { "role": "assistant", "content": "A surfer rides a wave on an open stretch of ocean under a clear sky." },
          "finish_reason": "stop" }
      ],
      "usage": { "completion_tokens": 18 } },
    { "prompt_index": 2,
      "completions": [
        { "index": 0,
          "message": { "role": "assistant", "content": "No one picks up an object during the clip; the surfer keeps both hands free while riding the wave. Nothing is lifted from the water, the board, or the shore." },
          "finish_reason": "stop" }
      ],
      "usage": { "completion_tokens": 70 } }
  ],
  "usage": {
    "prompt_tokens": 35612,
    "completion_tokens": 94,
    "total_tokens": 35706,
    "prompt_tokens_details": { "cached_tokens": 25872 }
  }
}
```

A prompt that fails returns an `error` object in place of its `completions`; other prompts are unaffected. The call returns `200` if at least one prompt succeeded; if all prompts fail, the whole request returns the first error's status. See [Handling partial failures](/perceptron-mk1/guides/multilook#handling-partial-failures) for an example and client code.

`cached_tokens` is the subset of `prompt_tokens` served from the in-request prefill. Reuse is scoped to the call: a subsequent identical call reports `cached_tokens: 0`. Billing rates and a worked example are in the guide's [Billing](/perceptron-mk1/guides/multilook#billing) section.

## Limits

| Limit                                | Value                                                                                       |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| Prompts per call                     | 1–16                                                                                        |
| Completions per call (`prompts × n`) | 64                                                                                          |
| Image/video inputs per call          | 256 (each video frame counts as one)                                                        |
| Request body size                    | 20 MB                                                                                       |
| Requests                             | 150/min (separate bucket from `/v1/chat/completions`)                                       |
| Request budget                       | 300 s — on timeout, retry with fewer prompts, lower `n`, or smaller `max_completion_tokens` |

<Callout type="info">
  Need higher limits? Contact [support@perceptron.inc](mailto:support@perceptron.inc).
</Callout>


## 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
      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:
                  code: null
                  message: 'Invalid n: 12. Expected a value between 1 and 8.'
                  param: null
                  type: invalid_request_error
        '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 or quota exceeded. Too many requests or
            insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Organization rate limit exceeded (300 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:
    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`.

            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.
          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.
        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
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestUserMessage'
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - user
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestAssistantMessage'
            - type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum:
                    - assistant
      description: >-
        Author role of the message as defined by the OpenAI Chat Completions
        spec.
    MultilookPromptInput:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/MultilookStructuredPrompt'
      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).
    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_thinking:
          type:
            - boolean
            - 'null'
          description: Toggle reasoning ("thinking") on supported models.
        internal_tools:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/InternalTools'
              description: Internal-tool toggles.
    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
    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
    InternalTools:
      type: object
      description: Internal-tool toggles for Perceptron vision models.
      properties:
        focus:
          type:
            - boolean
            - 'null'
          description: When true, allows the model to invoke its internal "focus" tool.
    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: >-
        Cached-token detail nested inside `usage`, following the OpenAI
        convention.
      required:
        - cached_tokens
      properties:
        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
        - type: array
          items:
            $ref: '#/components/schemas/ChatCompletionRequestSystemMessageContentPart'
      description: >-
        Chat completion message content as either a string or structured content
        array.
    ChatCompletionRequestUserMessageContent:
      oneOf:
        - type: string
        - type: array
          items:
            $ref: '#/components/schemas/ChatCompletionRequestUserMessageContentPart'
      description: >-
        Chat completion message content as either a string or structured content
        array.
    ChatCompletionRequestAssistantMessageContent:
      oneOf:
        - type: string
        - type: array
          items:
            $ref: >-
              #/components/schemas/ChatCompletionRequestAssistantMessageContentPart
      description: >-
        Chat completion message 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
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartImage
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - image_url
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartVideo
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - video_url
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartVideoFrames
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - video_frames
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartImageFileId
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - image_file_id
        - allOf:
            - $ref: >-
                #/components/schemas/ChatCompletionRequestMessageContentPartVideoFileId
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - video_file_id
    FinishReason:
      type: string
      enum:
        - stop
        - length
        - tool_error
        - tool_limit
    ChatCompletionResponseMessage:
      type: object
      description: Message object returned in the assistant's response.
      required:
        - role
      properties:
        content:
          type:
            - string
            - 'null'
        reasoning_content:
          type:
            - string
            - 'null'
        role:
          $ref: '#/components/schemas/Role'
    ChatCompletionRequestSystemMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
    ChatCompletionRequestAssistantMessageContentPart:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
    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'
    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
    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

````