Skip to main content

​
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="isaac-0.2-2b-preview") # or "qwen3-vl-235b-a22b-thinking"
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

SymptomFix
AuthErrorRecheck environment variables, or pass api_key directly to perceptron.configure.
TimeoutErrorAllowlist the hostname or route through your proxy; bump timeout via perceptron.config.
SSL certificate errorPoint 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.