Get a key
Reuse the user’s confirmed project. Inject its key asPYAI_API_KEY through a
secret manager or a private local .env file excluded from Git. Keep keys out
of browser bundles, agent prompts, copied terminal commands and shell tracing.
Do not print environment variables or credential files to discover a key.
If the user explicitly requests a new isolated sandbox, the CLI can create
one and save its credential privately without printing it:
env -u flags prevent an inherited key or endpoint from overriding that
profile. Never print the raw response from POST /v1/sandbox/keys: it contains
the credential. Hosted MCP does not expose sandbox-key creation.
A saved CLI profile does not export PYAI_API_KEY for SDKs or curl. Use the
CLI’s file workflows with that profile, or securely
inject an existing key before running the REST/SDK examples below. Browser
login also saves a CLI profile; it does not populate the shell environment.
Verify the project and usage before a first call
With the intended key already injected, inspect it without generating audio:org_id and project_id to the intended project. Check env, active
status, expiry, and the speak:synthesize / hear:transcribe scopes. Inspect
credit, key_budget_cents and effective limits; a test label, disabled
credit gate or null budget is not proof of an enforced spend/usage cap. Some
organizations are exempt from normal sandbox limits. Confirm the user’s
allowed spend and bound request count, input length and runtime before usage.
For live-project rates, see pricing.
Make a first call
After those checks and within the authorized usage bounds, save a speech file:stream: false returns a complete WAV with finalized length fields. Buffering
a streaming response alone can leave the duration unspecified in its header.
Transcribe a recording you are authorized to process:
Download a complete starter
Every starter includes the entry point, dependencies,.env.example, and run
instructions. These download URLs do not require access to an internal repo.
Python and TypeScript exercise Speak and optionally Hear. The LiveKit starter
tests its TTS adapter without a room; the Pipecat starter runs a text-to-audio
pipeline. Their detailed guides cover conversational agents. Twilio requires
your phone number, auth token, and a public HTTPS server or tunnel.
Use TypeScript SDK/CLI 0.18.1 for the downloadable Speak/Hear starter
and the Omni recipe (
pyai recipes omni, pyai init --template omni).
Python 0.5.1 is a separate package with its own API. Buffered speech returns
complete files; use each SDK’s streaming method for incremental delivery.
The TypeScript starter requires Node 22+; the generated Omni starter supports
Node 20.19+ with its included WebSocket transport. REST-only SDK use supports
Node 18+. Follow the chosen starter’s runtime and package contract.
MCP has an independent version: hosted HTTP is updated by PyAI; local stdio uses
the installed @pyai/mcp package. Neither the SDK pin nor the public
release manifest proves which MCP version
a connected host is running. Reconnect and inspect its tools after an update.
Connect a coding agent
For a complete saved-file workflow, follow Generate, play and transcribe audio in Cursor or Claude Code. It includes project verification, the tested CLI transcription fallback and safe recovery. These commands connect your coding agent to PyAI’s hosted HTTP MCP endpoint. Finish browser OAuth and select the intended organization and project; these commands do not start a local server or create a production key. Claude Code:.cursor/mcp.json, preserving existing servers:
get_started, whoami and list_voices.
Tool execution follows your coding agent’s permissions and the project you approved.
Before any generation, inspect whoami for project ID, environment, scopes,
credit and limits. A test label or null budget is not a zero-cost guarantee.
For local stdio instead, install Node.js 22+, run pyai login with the
intended project, then configure your host to launch npx -y @pyai/mcp as its
command. This is a separate transport from the hosted HTTP commands above.
create_sandbox_key is local-only, requires an explicit request, creates a
separate sandbox, and never returns its secret to the model; it is unavailable
on hosted HTTP. Do not replace an existing confirmed test project with a new one.
Paste this task into your agent: