Skip to main content
PyAI provides speech-to-text (STT) through Hear, text-to-speech (TTS) through Speak, and voice agents through Omni. This quickstart generates a short speech file, then transcribes it using the same API key. You need: a terminal with curl, a PyAI API key, and permission to use the selected project. The examples run on your server or local machine.

Step 1, get a key

Use an existing key from PyAI Console. If you already have a project, keep using its key so requests stay in that project. Inject PYAI_API_KEY through your secret manager or a private local environment file excluded from Git. Do not paste the real key into an agent prompt or a terminal command captured by an agent, and keep shell tracing disabled.
Only create a new isolated sandbox when requested. The CLI saves its credential privately and omits it from terminal output:
Choose an unused profile name for creation. Each creation makes a separate sandbox. Reuse this profile rather than minting another key. Clearing the inherited key and endpoint ensures these commands use the named profile. Never print the raw sandbox-key API response: it contains the credential. Hosted MCP does not expose sandbox-key creation.A CLI profile does not export an environment variable for curl or SDKs. Use CLI file workflows with this profile, or securely inject an existing key for the curl examples below. See Authentication.
Before any generation, inspect the already-injected key:
Match org_id and project_id to the intended project. Check env, active status, expiry, scopes, effective limits, credit and key_budget_cents. The examples need speak:synthesize and hear:transcribe. A test label, disabled credit gate or null budget does not establish an enforced spending cap; some organizations are exempt from normal sandbox limits. Confirm allowed spend and bound request count, input length and runtime before generating. For live-project rates, see pricing. Keep keys server-side; browser apps use their product’s short-lived token flow.
Check GET /v1/me for the scopes your workflow needs. Manage key scopes in the console; each product guide explains any additional setup.

Step 2, make a request

Text-to-speech (Speak)

Send text to POST /v1/audio/speech and save the returned audio bytes. The example selects stock_dorit_en_us, which is also the default when voice is omitted. Set a voice explicitly to keep your application’s choice stable:
Expected: 200 OK with a WAV body, saved as speech.wav. Play it with your audio player. stream: false finalizes the WAV length fields for duration readers. The response is audio bytes, not JSON or a download URL. If curl fails, inspect the error response instead of playing the output file. The maximum input is 2,000 characters per request. Continue with the TTS API guide for Python and TypeScript examples, voices, streaming, formats, and sample rates.

Speech-to-text (Hear)

Transcribe the file you just created, or replace speech.wav with a recording you are authorized to process:
Expected shape: a JSON object with the recognized text. Capitalization and punctuation may vary:
Omitting language requests automatic detection. For a known language, add -F language=en or another supported code. Use async STT jobs when you need timestamps, speaker labels, SRT/VTT, or a notification when transcription is ready.

Troubleshoot your first request

See Errors and limits for response shapes and retry rules. Synchronous STT uses multipart field file; async STT uploads use audio. Only the speech and transcription compatibility endpoints use OpenAI-shaped requests; other PyAI APIs have their own documented contracts.

Next steps

STT API

Choose file, streaming, or async transcription.

TTS API

Choose a voice and stream or save speech.

Python and TypeScript SDKs

Install an SDK and use the same API key.

Coding agents and MCP

Connect your coding assistant and download complete starters.

Voice agents

Build and run a complete conversation through the console or API.

Choose another workflow

Cloning, expressive speech, dubbing, call intelligence, and frameworks.
Use the API reference for exact fields and schemas, webhooks for signed completion notifications, and production readiness before moving customer traffic.