Get started with Python

Use the Perceptron Python SDK to send image, video, and audio messages to the hosted API. These guides use SDK 0.4.0 or later. You do not need a local GPU.

Set up your environment

Create a virtual environment, activate it, and install the client:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade "perceptron>=0.4.0"
export PERCEPTRON_API_KEY="your-api-key"

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1 and set the key with $env:PERCEPTRON_API_KEY="your-api-key". See Authentication for key configuration and troubleshooting.

Send an image request

Save this as first_request.py. It uses a public sample image and checks that the model finished its answer before printing it:

import os

from perceptron import Client, image

client = Client(
    api_key=os.environ["PERCEPTRON_API_KEY"],
    provider="perceptron",
    timeout=60.0,
)
response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=[{
        "role": "user",
        "content": [
            image(
                "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/"
                "main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
            ),
            {"type": "text", "text": "Describe this coastal scene and the visible objects."},
        ],
    }],
    max_completion_tokens=1024,
)

choice = response.choices[0]
if choice.finish_reason != "stop" or choice.message.tool_calls:
    raise RuntimeError(f"No completed text answer: {choice.finish_reason}")
print(choice.message.content or "")
if response.usage is not None:
    print(response.usage.to_dict())

Run it from the same terminal:

python first_request.py

With provider="perceptron", the SDK uses https://api.perceptron.inc/v1 unless you configure a different base_url. It can read PERCEPTRON_API_KEY automatically; the example passes the key explicitly. Requests are not retried automatically. Use the bounded retry example in Error messages when adding retries to your application.

Use a task helper

For a single question, question() builds the messages for you. Use image(), video(), or audio() to identify the media type:

from perceptron import image, question

result = question(
    image(
        "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/"
        "main/cookbook/_shared/assets/capabilities/qna/studio_scene.webp"
    ),
    "Describe this coastal scene and the visible objects.",
    provider="perceptron",
    model="perceptron-mk1.5",
    max_tokens=1024,
)
if not result.complete or result.finish_reason != "stop" or result.tool_calls:
    raise RuntimeError("No completed text answer")
print(result.text)

The helper returns a PerceiveResult; the message API returns a ChatCompletion. Both expose text, reasoning, tool calls, completion status, and asset resolution. The message API exposes typed Usage through response.usage; task helpers expose usage as a dictionary through result.usage. Use the message API when you need explicit conversation history or a tool loop.

Build on the example

Request basics: reusable functions, message roles, and follow-up questions.
Files: upload local media and reuse its file ID.
Multiple assets: include several images or videos and interpret asset_idx.
Structured outputs: validate a JSON result.
Tool calling: execute application functions and return their results.
Python FAQs: async requests, annotations, streaming, and common setup problems.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Set up your environment

Send an image request

Use a task helper

Build on the example

​Set up your environment

​Send an image request

​Use a task helper

​Build on the example

Set up your environment

Send an image request

Use a task helper

Build on the example