Skip to main content
POST
Create multilook chat completions

Overview

A multilook request carries a shared context and up to 16 prompts. The context uses the same message format as /v1/chat/completions, including media parts (image_url, video_url, video_frames, image_file_id, video_file_id). 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 covers when to use it, how billing works, and Python client code.

Request

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:
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 in the guide for a full example.

Response

One entry per prompt, in request order:
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 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 section.

Limits

Need higher limits? Contact support@perceptron.inc.

Authorizations

Authorization
string
header
required

Bearer token authentication using your Perceptron API key

Body

application/json

Request body for /v1/chat/completions/multilook.

context
(System · object | Developer · object | User · object | Assistant · object | Tool · object)[]
required

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.

Author role of the message: system, developer, user, assistant, or tool.

model
string
required

The model to invoke.

prompts
(string | Structured prompt · object)[]
required

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.

Required array length: 1 - 16 elements

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

frequency_penalty
number<float> | null

Positive values discourage the model from repeating previously used tokens.

Required range: -2 <= x <= 2
max_completion_tokens
integer<int32> | null

Maximum completion tokens, per completion. Must fit within the selected model's output limit.

Required range: x >= 0
n
integer<int32> | null
default:1

Sampled completions ("looks") per prompt (1 to 8). n > 1 requires temperature > 0.

Required range: 1 <= x <= 8
presence_penalty
number<float> | null

Positive values encourage the model to introduce new concepts.

Required range: -2 <= x <= 2
reasoning_effort
null | enum<string>

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.

Available options:
none,
minimal,
low,
medium,
high
temperature
number<float> | null

Sampling temperature, shared across all prompts.

Required range: 0 <= x <= 2
top_k
integer<int32> | null

Top-k sampling.

Required range: x >= 0
top_p
number<float> | null

Nucleus sampling probability.

Required range: x <= 1
vision_config
null | object

Perceptron vision-model controls, shared across all prompts.

Response

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.

Response body for /v1/chat/completions/multilook.

id
string
required
model
string
required
object
string
required

Always chat.completion.multilook.

results
object[]
required

One entry per prompt, in request order.

usage
null | object

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.