Skip to main content
POST
/
v1
/
chat
/
completions
cURL
curl --request POST \
  --url https://api.perceptron.inc/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "isaac-0.2-2b-preview",
  "messages": [
    {
      "role": "system",
      "content": "<hint>THINK</hint>"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
          }
        },
        {
          "type": "text",
          "text": "What stands out in this scene?"
        }
      ]
    }
  ]
}
'
{
  "choices": [
    {
      "index": 1,
      "message": {
        "content": "<string>",
        "reasoning_content": "<string>"
      }
    }
  ],
  "created": 1,
  "id": "<string>",
  "model": "<string>",
  "object": "<string>",
  "usage": {
    "completion_tokens": 1,
    "prompt_tokens": 1,
    "total_tokens": 1
  }
}

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.

​
Overview

The Chat Completions API is fully compatible with OpenAI’s chat completions specification, supporting both text-only and multimodal (image) requests. Use it to generate responses from Isaac 0.2. Isaac 0.2 triggers thinking and structured grounding through <hint>...</hint> tags inside a system-role message.

​
<hint> system messages

Place hint values inside a system-role message. Multiple hints can share one <hint> tag, separated by spaces.
HintOutput
<hint>BOX</hint>Bounding boxes
<hint>POINT</hint>Points / keypoints
<hint>POLYGON</hint>Polygon masks
<hint>THINK</hint>Chain-of-thought reasoning
<hint>FOCUS</hint>Enable internal focus tool

​
Example: Grounded detection

curl https://api.perceptron.inc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "isaac-0.2-2b-preview",
    "messages": [
      { "role": "system", "content": "<hint>BOX</hint>" },
      { "role": "user",
        "content": [
          { "type": "image_url",
            "image_url": { "url": "<image-url>" } },
          { "type": "text",
            "text": "Find every worker wearing PPE." }
        ]
      }
    ]
  }'

​
Example: Counting with grounding

For counting tasks or multi-step spatial reasoning, combining THINK with BOX (or POINT) is helpful on Isaac 0.2. For pure detection without counting, use the spatial hint alone. 
curl https://api.perceptron.inc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "isaac-0.2-2b-preview",
    "messages": [
      { "role": "system", "content": "<hint>BOX THINK</hint>" },
      { "role": "user",
        "content": [
          { "type": "image_url",
            "image_url": { "url": "<image-url>" } },
          { "type": "text",
            "text": "Count the safety violations and box each one. Explain your reasoning." }
        ]
      }
    ]
  }'

​
Example: OCR without hints

For free-form text tasks like OCR, no hint is needed — just send your prompt. 
curl https://api.perceptron.inc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "isaac-0.2-2b-preview",
    "messages": [
      { "role": "user",
        "content": [
          { "type": "image_url",
            "image_url": { "url": "<image-url>" } },
          { "type": "text",
            "text": "Extract each produce label along with its listed price." }
        ]
      }
    ]
  }'

​
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]. 
curl https://api.perceptron.inc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
    "model": "isaac-0.2-2b-preview",
    "messages": [
      { "role": "user",
        "content": [
          { "type": "image_url",
            "image_url": { "url": "<image-url>" } },
          { "type": "text", "text": "Describe this scene in detail." }
        ]
      }
    ],
    "stream": true,
    "stream_options": { "include_usage": true }
  }'

​
Best Practices

  1. Combining THINK with BOX/POINT is helpful for counting. Use the spatial hint alone for pure detection; add THINK when you need step-by-step reasoning alongside the bounding boxes.
  2. Leave temperature unset. The default is 0.0 (deterministic). Only set a non-zero value if you want more varied outputs.
  3. Image format: HTTP(S) URLs and base64 data URLs are both supported. MIME types: image/png, image/jpeg, image/webp.
  4. Token limits: 8K context.

​
Limits

LimitValue
Requests300/min
Request body size20 MB
Media upload20 GB per 48 hours
For large images, resize client-side before uploading. See the Tokenization guide for optimization tips.

Authorizations

​
Authorization
string
header
default:Bearer $PERCEPTRON_API_KEY
required

Bearer token authentication using your Perceptron API key

Body

application/json
​
messages
(User message · object | System message · object | Assistant message · object)[]
required

Conversation history listed in order. Supported roles: system, user, assistant.

Author role of the message as defined by the OpenAI Chat Completions spec.

Example:
[
  {
    "role": "system",
    "content": "<hint>THINK</hint>"
  },
  {
    "role": "user",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
        }
      },
      {
        "type": "text",
        "text": "What stands out in this scene?"
      }
    ]
  }
]
​
model
string
default:isaac-0.2-2b-preview
required

The model to invoke. Available options: isaac-0.2-2b-preview, isaac-0.2-1b, isaac-0.1, perceptron-mk1.

Example:

"isaac-0.2-2b-preview"

​
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 number of completion tokens to generate. Isaac 0.2 (1B and 2B Preview) has an 8K context window shared between input and output.

Required range: x >= 0
Example:

1024

​
presence_penalty
number<float> | null

Positive values encourage the model to introduce new concepts.

Required range: -2 <= x <= 2
​
regex
string | null

Regex pattern for constrained generation.

​
response_format
object

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.

​
stream
boolean | null
default:false

Set to true for SSE streaming. When omitted, the API returns a single JSON response.

​
stream_options
object

Optional streaming flags. Set include_usage: true to receive token counts in the final stream chunk.

​
temperature
number<float> | null
default:0

Sampling temperature. Lower values yield deterministic replies; higher values explore more creative outputs.

Server default is 0.0 for all Perceptron models (perceptron-mk1, isaac-0.1, isaac-0.2-1b, isaac-0.2-2b-preview). Omit the field unless you specifically want non-deterministic sampling.

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

Top-k sampling. The model samples from the top k most likely tokens.

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

Nucleus sampling probability. The model samples from the smallest token set whose cumulative probability exceeds this threshold.

Required range: x <= 1
​
vision_config
object

Perceptron vision-model controls (thinking, spatial output format, internal-tool toggles). Recommended for perceptron-mk1. Isaac-series models (isaac-0.1, isaac-0.2-1b, isaac-0.2-2b-preview) use <hint>...</hint> system messages instead.

Response

Chat completion generated successfully.

Non-streaming response body when stream=false.

​
choices
object[]
required
​
created
integer<int64>
required
Required range: x >= 0
​
id
string
required
​
model
string
required
​
object
string
required
​
usage
object

Token accounting emitted with every completion.