Multilook: many prompts, one context

Multilook sends one shared context — an image, a video, a few reference frames, or any message sequence you would pass to /v1/chat/completions — together with up to 16 independent prompts. The context is prefilled once and reused across every prompt, and the reused tokens are billed at the reduced cache-read rate. Each prompt gets its own completions, in request order, without seeing any other prompt.

Multilook Chat Completions

Full field reference, response shape, and request limits.

Pricing

Input, output, and cached-input rates for Perceptron Mk1.

When to use it

Reach for Multilook whenever several questions share the same media:

Checklists and rubrics — run every item of an inspection checklist over one clip in a single call.
Unrelated questions about one input — count people, describe the setting, and flag an action, without re-sending the video three times.
Sampling several looks — set n > 1 to draw multiple completions per prompt for self-consistency or majority voting.
Comparing prompt phrasings — send the same question worded several ways and compare the answers side by side.

Compared with issuing the same questions as separate /v1/chat/completions calls, one Multilook request bills the shared context at the cache-read rate for every prompt after the first, and counts as a single request against its own rate-limit bucket. Compared with client-side fan-out from the Batch guide, it removes the per-call media upload and the coordination code. Multilook is not the right tool when:

You need stream, response_format, or stop — none are supported on this endpoint.
Prompts depend on one another. Prompts are fully isolated: no prompt observes another prompt’s text or completions, so multi-turn conversations still belong on /v1/chat/completions.

How it works

context is prefilled once. It uses the same message format as /v1/chat/completions, including media parts (image_url, video_url, video_frames, image_file_id, video_file_id).
Each prompt is an implicit final user turn that extends the context. A prompt is either a bare string or { "content": [ ...parts ] } with the same part types as a user message.
Each prompt produces n completions (1–8), sampled with the same temperature, top_p, top_k, penalties, and vision_config for every prompt.
results[] comes back in request order. Each entry carries prompt_index plus either completions (with per-prompt usage.completion_tokens) or an error.
usage is reported once per call. prompt_tokens_details.cached_tokens is the subset of prompt_tokens served from the in-request prefill.

See the endpoint reference for every field and its constraints.

Quickstart

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
  }'

import os

import requests

VIDEO_URL = "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/main/cookbook/_shared/assets/tutorials/isaac_frame_by_frame/surf.mp4"

response = requests.post(
    "https://api.perceptron.inc/v1/chat/completions/multilook",
    headers={"Authorization": f"Bearer {os.environ['PERCEPTRON_API_KEY']}"},
    json={
        "model": "perceptron-mk1",
        "context": [
            {
                "role": "user",
                "content": [
                    {"type": "video_url", "video_url": {"url": VIDEO_URL}},
                ],
            }
        ],
        "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,
    },
    timeout=300,  # matches the server-side request budget
)
response.raise_for_status()
data = response.json()

for result in data["results"]:
    if result.get("error"):
        print(f"prompt {result['prompt_index']} failed: {result['error']['message']}")
        continue
    for completion in result["completions"]:
        print(result["prompt_index"], completion["index"], completion["message"]["content"])

usage = data["usage"]
print(
    f"prompt={usage['prompt_tokens']} "
    f"cached={usage['prompt_tokens_details']['cached_tokens']} "
    f"completion={usage['completion_tokens']}"
)

Per-prompt media

A prompt can carry its own content parts, including images or video. Use this when every prompt shares a reference but also brings its own input — for example, comparing a batch of parts against one approved sample:

{
  "model": "perceptron-mk1",
  "context": [
    { "role": "system",
      "content": "You are a QA inspector. Answer yes or no, then explain in one sentence." },
    { "role": "user",
      "content": [
        { "type": "text", "text": "Reference image of an approved part:" },
        { "type": "image_file_id", "image_file_id": { "file_id": "file-abc123" } }
      ]
    }
  ],
  "prompts": [
    { "content": [
        { "type": "image_url", "image_url": { "url": "https://example.com/part-001.jpg" } },
        { "type": "text", "text": "Does this part match the reference?" }
      ]
    },
    { "content": [
        { "type": "image_url", "image_url": { "url": "https://example.com/part-002.jpg" } },
        { "type": "text", "text": "Does this part match the reference?" }
      ]
    },
    "What makes the reference part acceptable?"
  ],
  "max_completion_tokens": 96
}

The reference image in context is prefilled once and shows up in cached_tokens. The per-prompt images (part-001.jpg, part-002.jpg) sit outside the shared prefix: they are fetched, preprocessed, and prefilled per prompt, and are not reported in cached_tokens. Media you intend to reuse across prompts belongs in context. File ids work in both places. See Working with files for uploading media once and referencing it by id.

Sampling multiple looks (`n > 1`)

Set n (1–8) to draw several completions per prompt. Two constraints apply:

n > 1 requires temperature > 0. temperature defaults to 0.0, so set it explicitly.
prompts × n must not exceed 64 completions per call.

Completions for n > 1 do not re-bill prompt tokens — you pay only for the extra output. A simple majority vote over the sampled looks:

from collections import Counter

for result in data["results"]:
    if result.get("error"):
        continue
    answers = [c["message"]["content"].strip() for c in result["completions"]]
    winner, votes = Counter(answers).most_common(1)[0]
    print(f"prompt {result['prompt_index']}: {winner!r} ({votes}/{len(answers)} looks agree)")

Handling partial failures

A prompt that fails returns an error object in place of its completions. The other prompts are unaffected, and the call still returns 200 as long as at least one prompt succeeded. If every prompt fails, the whole request returns the first error’s status.

{
  "id": "mlcmpl-7f3a2c",
  "object": "chat.completion.multilook",
  "model": "perceptron-mk1",
  "results": [
    { "prompt_index": 0,
      "completions": [
        { "index": 0,
          "message": { "role": "assistant", "content": "Yes. The part matches the reference." },
          "finish_reason": "stop" }
      ],
      "usage": { "completion_tokens": 9 } },
    { "prompt_index": 1,
      "error": {
        "type": "invalid_request_error",
        "code": null,
        "message": "Could not fetch image at https://example.com/part-002.jpg (HTTP 404)."
      } },
    { "prompt_index": 2,
      "completions": [
        { "index": 0,
          "message": { "role": "assistant", "content": "It has no visible scratches and the mounting holes are aligned." },
          "finish_reason": "stop" }
      ],
      "usage": { "completion_tokens": 14 } }
  ],
  "usage": {
    "prompt_tokens": 4212,
    "completion_tokens": 23,
    "total_tokens": 4235,
    "prompt_tokens_details": { "cached_tokens": 2604 }
  }
}

The error.type and error.code values above are illustrative. Branch on the presence of error rather than on specific codes.

succeeded, failed = [], []
for result in data["results"]:
    if result.get("error"):
        failed.append((result["prompt_index"], result["error"]["message"]))
    else:
        succeeded.append(result)

for index, message in failed:
    print(f"prompt {index} failed: {message}")

Other things to plan for:

Request budget: each call has 300 seconds to finish. On a timeout, retry with fewer prompts, a lower n, or a smaller max_completion_tokens.
Rate limits: Multilook has its own 150 requests/min bucket, separate from /v1/chat/completions. Handle 429 with backoff as described in the Scaling guide.

Billing

Each call produces one usage event, billed at Perceptron Mk1’s standard rates:

prompt_tokens − cached_tokens — $0.15 / M tokens (input rate)
cached_tokens — $0.0375 / M tokens (cache-read rate)
completion_tokens — $1.50 / M tokens (output rate)

prompt_tokens counts the shared context once per prompt, matching /v1/chat/completions accounting. cached_tokens is the part of that total served from the in-request prefill, and it approaches (P − 1) / P of prompt_tokens for P prompts as each prompt’s own text becomes small relative to the context. Reuse is scoped to the call: a subsequent identical call reports cached_tokens: 0. Worked example. Four prompts over one ~60-frame video (~8,900 context tokens each) bill 35,612 prompt tokens, of which 25,872 are at the cache-read rate, plus 94 completion tokens:

	Tokens	Rate	Cost
Uncached input (`prompt_tokens − cached_tokens`)	9,740	$0.15 / M	$0.00146
Cached input (`cached_tokens`)	25,872	$0.0375 / M	$0.00097
Output (`completion_tokens`)	94	$1.50 / M	$0.00014
Total			≈ $0.0026

The same four questions as four separate /v1/chat/completions calls would bill all 35,612 prompt tokens at the input rate — about $0.0055 in total, roughly twice the cost. Figures are illustrative; actual token counts depend on your media and prompts.

Limits

All request limits — prompts per call, completions per call, media inputs, body size, rate limit, and request budget — are listed on the endpoint page.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Multilook

Multilook: many prompts, one context

Multilook Chat Completions

Pricing

When to use it

How it works

Quickstart

Per-prompt media

Sampling multiple looks (`n > 1`)

Handling partial failures

Billing

Limits

​Multilook: many prompts, one context

Multilook Chat Completions

Pricing

​When to use it

​How it works

​Quickstart

​Per-prompt media

​Sampling multiple looks (n > 1)

​Handling partial failures

​Billing

​Limits

Multilook: many prompts, one context

When to use it

How it works

Quickstart

Per-prompt media

Sampling multiple looks (`n > 1`)

Handling partial failures

Billing

Limits