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. InjectPYAI_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.
Need a sandbox key?
Need a sandbox key?
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.
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.
Using this key with other PyAI products?
Using this key with other PyAI products?
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 toPOST /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:
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 replacespeech.wav with a recording
you are authorized to process:
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.