x-api-key: pyai_live_... is an accepted alias for environments where setting an
Authorization header is awkward.
Environments
No signup:
POST /v1/sandbox/keys returns a pyai_test_ key
in api_key. Keep that response private: the quickstart uses the
CLI to save the credential without printing it. Test keys skip the credit gate.
Ordinary sandboxes have daily and concurrency limits, but some organizations
are exempt. Inspect GET /v1/me for the actual project, scopes, credit,
key_budget_cents and effective limits before usage. A null budget or missing
cap is not an enforced spending limit; retain the user’s request/runtime bounds.
Because the mint asks for no email, password or card, it is capped per source
network: 2 keys per rolling 24 hours, after which it returns
429 sandbox_limit_reached until the oldest ages out. Keep
the key you mint (in CI, put it in a secret) rather than minting a fresh one per
run, and see account-creation limits
if you share an egress and need the network raised.
Create a longer-lived key in the console. The secret
is shown once. Store it as an environment variable, never in source control.
Scopes
Keys carry scopes that gate which products they can call:GET /v1/models and GET /v1/voices are catalog reads, any active key may call
them. A request whose key lacks the required scope returns 403 forbidden.
Cue is unavailable. There is no active Cue scope or grounding behavior on the
Hear streaming route.
WebSocket authentication
Keep long-lived API keys on your server, including test keys. WebSocket subprotocols are visible in client code and request inspection; they do not make a secret safe to expose in a browser. For Omni browsers, your authenticated backend callsPOST /v1/omni/sessions
(or SDK omni.createSession) with an explicit allowed_origins allowlist and
ttl_seconds (default 60, maximum 600). Return only the short-lived session
response to the browser:
omni:session only and one concurrent connection. Expiry controls credential
validity, not a spending ceiling or maximum conversation duration.
Server-side clients use the SDK with a key from their secret environment.
PyAI selects only pyai.v1 in the response; the credential is still present in
the request. Prefer SDK authentication over the legacy server-only api_key
query fallback. For Hear or other browser integrations, proxy through your
backend unless that product documents a suitable scoped browser credential;
an Omni session token does not grant Hear access.
Rotation & revocation
Each key in the console has rotate and revoke controls.- Rotate issues a new secret and invalidates the old one.
- Revoke disables the key everywhere within 60 seconds.
401 unauthorized.
What errors look like
Data-plane auth failures use the OpenAI envelope. Branch onerror.code. Do
not retry these.
Missing or revoked key (401). The gateway code is invalid_api_key (or
missing_api_key when the header is absent):
403). A sandbox mint hitting Clone
looks like this (speak:clone is not on POST /v1/sandbox/keys):
GET /v1/me and read scopes before you retry. Signup keys include
speak:clone; sandbox mint keys do not.
A pyai_live_ key on an org with no prepaid credit (402):
pyai_test_ keys skip the credit gate. They return
429 daily_cap_exceeded when the daily unit cap is hit instead.
See Errors and limits for the full code table and
Pricing for current rates and included usage.