Authentication

Every API request needs a Perceptron API key. Use a key from the organization that owns the files and other resources your application accesses.

Create an API key

Get your key from the Perceptron platform

Join Discord

Get help and see what others are building

Set the key in your environment

For Bash or Zsh:

export PERCEPTRON_API_KEY="your-api-key"

For Windows PowerShell:

$env:PERCEPTRON_API_KEY="your-api-key"

Start your Python process from that terminal. A notebook or editor that was already running may need its kernel or process restarted to receive the new environment variable.

Configure the Python client

The Perceptron SDK reads PERCEPTRON_API_KEY. You can also pass the key explicitly. Select the Perceptron provider for these guides:

import os

from perceptron import Client

client = Client(
    api_key=os.environ["PERCEPTRON_API_KEY"],
    provider="perceptron",
    timeout=60.0,
)

Reuse this client for requests with the same credentials. Create a separate client when using another organization’s key. The key is read when this code runs; changing the environment later does not update an existing client. timeout is a client setting, not a model parameter. The SDK does not automatically retry requests; its retries setting is accepted for compatibility but does not enable retries. See Error messages before adding a retry policy.

Authenticate an HTTP request

Direct HTTP requests use the Authorization header. For example, list the models:

curl --fail-with-body --silent --show-error \
  https://api.perceptron.inc/v1/models \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY"

Do not put the key in the URL, message content, or a media URL. Keep it in a server-side environment or secret store, exclude secret files from source control, and avoid logging authorization headers. Browser and mobile applications should call your backend rather than embed the API key in distributed code.

Resolve authentication problems

Symptom	Check
Python raises `KeyError: 'PERCEPTRON_API_KEY'`	Set the variable in the environment of the process running Python. No API request has been made.
`401`	Supply a valid, active Perceptron key in the bearer header. Check for copied whitespace or a revoked key.
`403`	Check the organization’s access to the requested resource.
`429`	Check the error type: rate limiting and exhausted credits need different responses.
A request goes to another provider	Set `provider="perceptron"`, check any configured `base_url` or `PERCEPTRON_BASE_URL`, and pass the Perceptron key to this client.

For error fields, diagnostic headers, and retry behavior, see Error messages.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Create an API key

Join Discord

Set the key in your environment

Configure the Python client

Authenticate an HTTP request

Resolve authentication problems

Create an API key

Join Discord

​Set the key in your environment

​Configure the Python client

​Authenticate an HTTP request

​Resolve authentication problems

Set the key in your environment

Configure the Python client

Authenticate an HTTP request

Resolve authentication problems