Skip to main content
Isaac 0.1 triggers grounding through <hint>...</hint> system messages. Reasoning and Focus are not supported on Isaac 0.1 — see Isaac 0.2 for those capabilities. See the API reference for details.

​
Quick reference

TaskSDK HelperOptimal Prompt
Concise captioncaption(style="concise")Provide a concise, human-friendly caption for the upcoming image.
Detailed captioncaption(style="detailed")Provide a detailed caption describing key objects, relationships, and context in the upcoming image.
OCRocr()System: You are an OCR system. Accurately detect, extract, and transcribe all readable text from the image.
General detectiondetect()Your goal is to segment out the objects in the scene
Class detectiondetect(classes=[...])Your goal is to segment out the following categories: {categories}
Visual Q&Aquestion()Pass your question directly as user content
Grounded Q&Aquestion(expects="box")Same question, model returns boxes with answers
Countingquestion()How many {objects} are there? Point to each.

​
Grounding on Isaac 0.1 (<hint> syntax)

Place hint values inside a system-role message.
HintOutput
<hint>BOX</hint>Bounding boxes
<hint>POINT</hint>Points
<hint>POLYGON</hint>Polygons

​
Example: boxes

curl -X POST "https://api.perceptron.inc/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
  "model": "isaac-0.1",
  "messages": [
    { "role": "system", "content": [{"type": "text", "text": "<hint>BOX</hint>"}] },
    { "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "<image-url>"}},
        {"type": "text", "text": "Find all the safety equipment"}
      ]
    }
  ]
}'

​
Example: points

curl -X POST "https://api.perceptron.inc/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -d '{
  "model": "isaac-0.1",
  "messages": [
    { "role": "system", "content": [{"type": "text", "text": "<hint>POINT</hint>"}] },
    { "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "<image-url>"}},
        {"type": "text", "text": "Point at each visible helmet"}
      ]
    }
  ]
}'

​
Advanced: @perceive decorator

The Python SDK wraps the chat-completions endpoint with a typed decorator that handles hint setup and result parsing for you.

​
Basic usage

from perceptron import configure, perceive, image, text

configure(provider="perceptron", api_key="YOUR_API_KEY")

@perceive(model="isaac-0.1")
def analyze(photo):
    return image(photo) + text("Identify the dominant colors in this scene")

result = analyze("scene.jpg")
print(result.text)

​
With structured output (Pydantic)

from pydantic import BaseModel
from perceptron import configure, perceive, pydantic_format, image, text

configure(provider="perceptron", api_key="YOUR_API_KEY")

class SceneAnalysis(BaseModel):
    primary_color: str
    object_count: int
    description: str

@perceive(model="isaac-0.1", response_format=pydantic_format(SceneAnalysis))
def analyze_scene(photo):
    return image(photo) + text("Analyze this image and return the structured result.")

scene = analyze_scene("photo.jpg")
print(scene.primary_color, scene.object_count)