Skip to main content
PyAI Hear transcribes audio, Speak synthesizes speech, and Omni runs a complete voice-agent conversation. Start with your existing language or framework.

Get a key

Reuse the user’s confirmed project. Inject its key as PYAI_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:
Use an unused profile name for creation. Each creation makes a separate sandbox; reuse the saved profile on later runs. The 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:
Match 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:
Omitting the Hear language hint enables automatic detection. Use the language support table to select a voice and confirm coverage.

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:
Codex:
Cursor: merge this entry into .cursor/mcp.json, preserving existing servers:
Open your client’s MCP tools view, enable the server if prompted, and ask it to finish browser authorization, then call 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:

Install the Markdown skill (optional)

Codex, from your project directory:
Claude Code, from your project directory:
Review the downloaded skill before using it; rerunning replaces that PyAI skill file. For other tools, attach the Markdown or give the agent its public URL. Setup references: Codex MCP, Codex skills, Cursor MCP, and Claude Code MCP.

Streaming and production

Consume audio chunks immediately; reuse clients and cancel interrupted streams. Use PCM, WAV or G.711 for streaming. MP3 and Opus are buffered. First received bytes and speaker playback latency are different measurements. For long recordings use async jobs. For callbacks read webhooks. Before deployment, follow production readiness. The OpenAPI contract and documentation index provide the complete API. For browser login, permissions, local profiles and chat app setup, use the MCP guide.