Authentication

To configure credentials, you can set environment variables directly in your code, use the configure() helper to set them for the process, or use the config() context manager to set them for a single context.

Environment variables

If you’re setting environment variables directly, you can set the following. The SDK will use them at runtime:

export PERCEPTRON_PROVIDER="perceptron" # for now, either "perceptron" or "fal"
export PERCEPTRON_API_KEY="<your_api_key_here>" # your Perceptron API key or Fal API key
export PERCEPTRON_BASE_URL="<optional_base_url_here>" # [optional] can include a separate base URL

Direct calls

If you’re using the configure() helper, you can pass in the credentials directly:

from perceptron import configure
configure(
    provider="perceptron",
    api_key="<your_api_key_here>",
    base_url="<optional_base_url_here>",
)

Context manager

You can also use the config() context manager when you need a one-off override—for example, to bump timeouts or retries around a specific call:

from perceptron import config

with config(timeout=60, retries=3):
    caption("inspection.png")

Configurable fields

Fields for configure() as a standalone function or the config() context manager:

Setting	Default	Description
`base_url`	`None`	Override the Perceptron endpoint (e.g., edge gateway).
`api_key`	`None`	API key to send with requests.
`provider`	`None` → auto-detected (`"fal"` when relevant)	Transport/provider name.
`model`	`None`	Preferred model ID if your provider exposes multiple versions.
`timeout`	`60.0`	Per-request timeout in seconds.
`retries`	`3`	Automatic retry attempts on transient errors.
`strict`	`False`	Enforce strict parsing (raises on schema mismatches).
`allow_multiple`	`False`	Allow multiple responses when the task permits it.
`warn_on_implicit_anchor`	`True`	Emit warnings if prompts rely on implicit spatial anchors.
`temperature`	`None`	Generation temperature for text answers.
`max_tokens`	`None`	Token cap for generations.
`top_p`	`None`	Nucleus sampling parameter.
`top_k`	`None`	Limits sampling to the top-k candidates when set.
`max_buffer_bytes`	`None`	Caps streamed buffer size (useful for long outputs).
`resize_max_side`	`None`	Downscale images so the longest side matches this value before upload.
`auto_coerce_paths`	`False`	Automatically open local file paths passed into SDK helpers.

Settings resolve in this order: per-call arguments → decorator defaults → configure / context manager → environment variables → library defaults.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Environment variables

Direct calls

Context manager

Configurable fields

​Environment variables

​Direct calls

​Context manager

​Configurable fields

Environment variables

Direct calls

Context manager

Configurable fields