Quickstart

PyAI is telephony-native Voice AI behind one API key: Omni, one realtime endpoint for a complete voice agent; Hear for speech-to-text; Speak for text-to-speech and cloning; Cue for turn detection and knowledge context in your own pipeline; AMD for answering-machine detection; and Trace for compliance guardrails. The API is OpenAI-compatible at https://api.pyai.com/v1.

Step 1, get a key

Fastest: an instant sandbox key, no signup, email, or card. It works immediately, skips the credit gate, and is bounded by daily caps:

export PYAI_API_KEY="$(
  curl -sS -X POST https://api.pyai.com/v1/sandbox/keys \
    | python -c 'import json,sys; print(json.load(sys.stdin)["api_key"])'
)"

Verify it in 5 seconds (GET /v1/me echoes the org, scopes, and credit posture your key resolves to):

curl https://api.pyai.com/v1/me -H "Authorization: Bearer $PYAI_API_KEY"

For production: create an account and mint a pyai_live_ key in the console. Live usage is billed against prepaid credit. HTTP auth accepts Authorization: Bearer <key> or the header alias x-api-key: <key>.

Fastest start: scaffold a complete, runnable example in one command, no clone, no setup ceremony.

npm create pyai-app@latest                   # pick an example interactively
npm create pyai-app@latest openai-drop-in     # already on OpenAI? migrate by changing the base URL

Browse them all at github.com/atomsai/pyai-examples.

Step 2, pick what you’re building

AI voice agent (Omni)

Replace the speech-to-text, LLM, text-to-speech, VAD, and turn-detection cascade with one WebSocket.

Speech-to-text (Hear)

Transcribe a file with one POST, or stream partials over WebSocket.

Text-to-speech (Speak)

Turn text into natural speech with stock, cloned, or designed voices.

Answering-machine detection (AMD)

Know who or what answered, human, voicemail, IVR, screening, with the reason. Twilio drop-in.

Compliance guardrails (Trace)

Rule packs (TCPA, HIPAA, PII) and per-call scorecards for your agents.

No code: Agents Beta

Configure, test, and connect an Omni voice agent from the console.

AI voice agent (Omni)

Omni is the complete voice agent behind one realtime endpoint. It hears, reasons, calls tools, grounds answers in your knowledge, and speaks back. Your app streams audio to one WebSocket instead of operating separate speech-to-text, LLM, text-to-speech, VAD, turn-detection, and interruption components. Start with the Omni overview, follow the browser tutorial, or configure and test an agent without code in the console. For every frame and event, use the wire protocol reference.

Speech-to-text (Hear)

One POST transcribes a file:

curl https://api.pyai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -F file=@audio.wav -F model=pyai-hear
# -> { "text": "..." }

Need live partials (voice bots, captions, agent assist)? Stream over WebSocket instead, first partial typically lands within ~300 ms: streaming STT guide. For large backlogs, the async batch API (POST /v1/transcription/jobs) is discounted vs. realtime.

Text-to-speech (Speak)

curl https://api.pyai.com/v1/audio/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"pyai-voice","input":"Hello from PyAI.","voice":"stock_dorit_en_us"}' \
  --output hello.wav

import os
from pyai import PyAI  # pip install pyai-sdk

pyai = PyAI(api_key=os.environ["PYAI_API_KEY"])
audio = pyai.audio.speech(input="Hello from PyAI.", voice="stock_dorit_en_us")
open("hello.wav", "wb").write(audio)

import PyAI from "@pyai/sdk"; // npm install @pyai/sdk

const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });
const audio = await pyai.audio.speech({ input: "Hello from PyAI.", voice: "stock_dorit_en_us" });
// write `audio` (ArrayBuffer) to hello.wav

voice is a stock voice id from GET /v1/voices (the curated prebuilt catalog with personas and avatars) or a cloned voice id from /v1/voice/clones. Omit it to use your account’s default voice. Migrating from OpenAI? The preset names alloy, echo, fable, onyx, nova, and shimmer work as drop-in aliases for PyAI stock voices, so existing code runs unchanged.

Answering-machine detection (AMD)

Already on Twilio? Point a Media Stream at wss://api.pyai.com/v1/amd/stream and get answered_by (human, voicemail, ivr, screening, …) plus the reason it decided, in a fraction of the dead-air dwell. Set the operating-point dial and webhook once:

curl -X POST https://api.pyai.com/v1/amd/config \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aggressiveness": 0.5, "webhook_url": "https://your-app.example.com/amd"}'

AMD needs a key with the amd:detect / amd:configure scopes (add scopes in the console), and bills per answered call, the first 5,000 each month are free. Full walkthrough: AMD guide.

Compliance guardrails (Trace)

Trace scans every agent call against built-in rule packs (TCPA, HIPAA, PII, brand-voice) and your own rules, then gives each call a scorecard with plain-English findings. Turn it on for your org (or one agent) with one PUT:

curl -X PUT https://api.pyai.com/v1/trace/config \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "rule_packs": { "tcpa": { "enabled": true }, "pii": { "enabled": true } },
    "guardrails": { "mode": "warn", "block_pii": { "patterns": ["ssn", "credit_card"] } }
  }'

Modes: warn logs only (never blocks), modify redacts PII / injects disclosures, block suppresses, human_handoff escalates. Always fail-open. Then read your exposure dashboard and per-call evidence:

curl "https://api.pyai.com/v1/trace/exposure?window_days=30" \
  -H "Authorization: Bearer $PYAI_API_KEY"

Trace needs a key with the trace:configure / trace:read scopes. It’s in beta, free during beta, and defaults to on in warn mode. Full walkthrough: Trace guide.

Prefer the official SDKs, they handle auth, retries, idempotency, and realtime for you: npm install @pyai/sdk or pip install pyai-sdk.

Next steps

Use-case build guides

Build your own Gong, a voice dictation app, an AI receptionist, or call-center QA, step by step.

Build a browser voice agent

Mic → Omni → speakers in ~10 minutes, all client-side.

Agent greeting messages

Set an opening line on an agent profile in the console, spoken at turn 0.

Omni tools & function calling

Give your agent real actions: order lookups, bookings, transfers.

AMD guide

Twilio Media Streams drop-in, tuning, and webhooks.

Authentication

Keys, environments, rotation, revocation.

Pricing & metering

How usage is measured and billed.

Errors & limits

Error codes, rate limits, idempotency.

API reference

Full request/response schemas, right here in the docs.

Runnable examples

Copy-paste apps, OpenAI drop-in, voice cloning, telephony, call analytics. npm create pyai-app@latest.

Get started

Omni

Guides

Integrations

Use cases

Reference

Step 1, get a key

Step 2, pick what you’re building

AI voice agent (Omni)

Speech-to-text (Hear)

Text-to-speech (Speak)

Answering-machine detection (AMD)

Compliance guardrails (Trace)

No code: Agents Beta

AI voice agent (Omni)

Speech-to-text (Hear)

Text-to-speech (Speak)

Answering-machine detection (AMD)

Compliance guardrails (Trace)

Next steps

Use-case build guides

Build a browser voice agent

Agent greeting messages

Omni tools & function calling

AMD guide

Authentication

Pricing & metering

Errors & limits

API reference

Runnable examples

​Step 1, get a key

​Step 2, pick what you’re building

AI voice agent (Omni)

Speech-to-text (Hear)

Text-to-speech (Speak)

Answering-machine detection (AMD)

Compliance guardrails (Trace)

No code: Agents Beta

​AI voice agent (Omni)

​Speech-to-text (Hear)

​Text-to-speech (Speak)

​Answering-machine detection (AMD)

​Compliance guardrails (Trace)

​Next steps

Use-case build guides

Build a browser voice agent

Agent greeting messages

Omni tools & function calling

AMD guide

Authentication

Pricing & metering

Errors & limits

API reference

Runnable examples

Step 1, get a key

Step 2, pick what you’re building

AI voice agent (Omni)

Speech-to-text (Hear)

Text-to-speech (Speak)

Answering-machine detection (AMD)

Compliance guardrails (Trace)

Next steps