Get started - Perceptron Docs

Install and verify

Install the SDK. Note that Python 3.9+ is required.

uv pip install perceptron

Confirm the version with pip show perceptron. Next, configure credentials and run a simple query.

import perceptron
from perceptron import perceive, image, text

perceptron.configure(
    provider="perceptron", # "perceptron" or "fal"
    api_key="<your_api_key_here>",
)

@perceive(model="perceptron-mk1")
def caption(image_path):
    return image(image_path) + text("Describe the primary object in this photo.")

result = caption("drone.png")
print(result.text)

The decorator compiles the Task JSON, sends the request, and returns a PerceiveResult object containing text, optional points, parsed segments, any errors, and the raw provider payload. Call result.points_to_pixels(width, height) when you need pixel-space coordinates from the normalized 0–1000 grid (more on this here).

First-run checklist

caption("drone.png").text returns content with no exception.
caption("drone.png").errors is empty (or populated with expected warnings).
Outbound network access to https://api.perceptron.inc succeeds.
Logs show retries or timeouts only when expected.

Troubleshooting reference

Symptom	Fix
`AuthError`	Recheck environment variables, or pass `api_key` directly to `perceptron.configure`.
`TimeoutError`	Allowlist the hostname or route through your proxy; bump `timeout` via `perceptron.config`.
SSL certificate error	Point `PERCEPTRON_BASE_URL` at the TLS endpoint your network trusts.

Looking for other languages or SDKs? Tell us in Discord so we can prioritize official releases.