Chat Completions
Overview
The Chat Completions API is fully compatible with OpenAI’s chat completions specification, supporting both text-only and multimodal (vision) requests. Use it to generate responses from Perceptron Mk1. Perceptron Mk1 triggers thinking and structured grounding through the typedvision_config body field.
vision_config
For perceptron-mk1, pass a top-level vision_config object alongside messages:
| Field | Values | Purpose |
|---|---|---|
annotation_format | "point" / "box" / "polygon" / "clip" | Grounded output format. clip is video-only. |
enable_thinking | true / false | Chain-of-thought reasoning. |
internal_tools.focus | true / false | Enable the focus tool — model can zoom into regions. Image only. |
When to enable_thinking
- On for text Q&A, captioning, OCR, and video clipping (
annotation_format: "clip"). - Off for spatial detection (
annotation_formatin"point","box","polygon").
Example: Grounded detection
Example: Video clipping
Example: Video from pre-decoded frames
If you’ve already sampled frames client-side, pass them inline with avideo_frames content part instead of a single video_url. Each frame carries an image_url (HTTP(S) URL or base64 data URL) and a timestamp_ms offset from the start of the clip. Provide between two and 256 frames, ordered by non-decreasing timestamp_ms. For optimal performance, follow a uniform sampling strategy aligned with the Video Token Counting guide.
Example: Image reasoning with focus
Streaming
Set"stream": true to receive Server-Sent Events (SSE). To get token usage, also set stream_options.include_usage: true — when enabled, usage is attached to the final chunk (the one with finish_reason: "stop"), immediately before data: [DONE].
Best Practices
- Thinking pairs well with text and clipping; not with spatial detection. Turn
enable_thinkingon for text Q&A, captioning, OCR, andannotation_format: "clip". Turn it off for"point","box", and"polygon". - Leave
temperatureunset. The default is0.0(deterministic). Only set a non-zero value if you want more varied outputs. - Image format: HTTP(S) URLs and base64 data URLs are both supported. MIME types:
image/png,image/jpeg,image/webp,video/mp4,video/webm. - Inline frames vs.
video_url: Send a whole clip withvideo_url, or — if you’ve already sampled frames — pass them inline withvideo_frames(two to 256 frames,timestamp_msnon-decreasing). Inline frames give you precise control over exactly which frames the model sees; for optimal performance, sample uniformly in line with the Video Token Counting guide. - Token limits: 32K context, 8K output.
Limits
| Limit | Value |
|---|---|
| Requests | 300/min |
| Request body size | 20 MB |
| Media upload | 20 GB per 48 hours |
Authorizations
Bearer token authentication using your Perceptron API key
Body
Conversation history listed in order. Supported roles: system, user, assistant.
Author role of the message as defined by the OpenAI Chat Completions spec.
- Option 1
- Option 2
- Option 3
The model to invoke. Available options: isaac-0.1, isaac-0.2-1b, isaac-0.2-2b-preview, perceptron-mk1.
Positive values discourage the model from repeating previously used tokens.
-2 <= x <= 2Maximum number of completion tokens to generate.
Model-specific limits:
- Isaac 0.1: The combined total of input tokens and output tokens must not exceed 8192 tokens.
x >= 0Positive values encourage the model to introduce new concepts.
-2 <= x <= 2Regex pattern for constrained generation.
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.
- Option 1
- Option 2
Set to true for SSE streaming. When omitted, the API returns a single JSON response.
Optional streaming flags. Token usage is always reported in the final chunk of a streaming response.
Sampling temperature. Lower values yield deterministic replies; higher values explore more creative outputs.
Model-specific recommendations:
- Isaac 0.1: Default and recommended value is
0.0.
0 <= x <= 2Top-k sampling. The model samples from the top k most likely tokens.
x >= 0Nucleus sampling probability. The model samples from the smallest token set whose cumulative probability exceeds this threshold.
x <= 1Perceptron vision-model controls (thinking, spatial output format, internal-tool toggles). Only supported on Perceptron-owned models.