> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Mint an instant key and ship your first PyAI call in minutes: an Omni voice agent, speech-to-text, text-to-speech, answering-machine detection, or Trace compliance guardrails.

PyAI is telephony-native Voice AI behind one API key: **Omni**, the all-in-one
voice agent model (hearing, reasoning, tool calling, and emotion-aware speech
over one WebSocket), **Hear** (speech-to-text), **Speak** (text-to-speech +
cloning), **Cue** (turn detection + knowledge-base context for your own
pipeline), the **AMD API** (answering-machine detection), and **Trace**
(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:

```bash theme={null}
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):

```bash theme={null}
curl https://api.pyai.com/v1/me -H "Authorization: Bearer $PYAI_API_KEY"
```

**For production:** [create an account](https://console.pyai.com/playground?signup=1\&path=api\&utm_source=docs.pyai.com\&utm_medium=docs)
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>`.

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

  ```bash theme={null}
  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](https://github.com/atomsai/pyai-examples).
</Note>

## Step 2, pick what you're building

<CardGroup cols={2}>
  <Card title="AI voice agent (Omni)" href="#ai-voice-agent-omni">One WebSocket: the agent hears, reasons, calls your tools, and speaks back. Nothing to create first.</Card>
  <Card title="Speech-to-text (Hear)" href="#speech-to-text-hear">Transcribe a file with one POST, or stream partials over WebSocket.</Card>
  <Card title="Text-to-speech (Speak)" href="#text-to-speech-speak">Turn text into natural speech with stock, cloned, or designed voices.</Card>
  <Card title="Answering-machine detection (AMD)" href="#answering-machine-detection-amd">Know who or what answered, human, voicemail, IVR, screening, with the reason. Twilio drop-in.</Card>
  <Card title="Compliance guardrails (Trace)" href="#compliance-guardrails-trace">Rule packs (TCPA, HIPAA, PII) and per-call scorecards for your agents.</Card>
  <Card title="No code: Agents Beta" href="/agents/getting-started">Configure, test, and connect an Omni voice agent from the console.</Card>
</CardGroup>

### AI voice agent (Omni)

Omni is the whole voice agent in one model, it hears, reasons with a fused LLM
brain, calls your tools, grounds answers in your knowledge base, and speaks
back in emotion-aware voices. It's **zero-state**: the session is authorized by
your key's org, so there's nothing to create first. Open a WebSocket, pass the
key as a subprotocol (browser-safe), and send the whole agent in one
`configure` frame: `voice_id`, `persona`, `kb_endpoint` (grounding), and
`tools[]` (function calling). Enable prebuilt **hosted tools** by name with
zero setup, `search_knowledge`, `web_search`, `weather`, `currency`,
`unit_convert`, `math`, `datetime`, `geocode`, `news`, or register your own
webhook ([Omni tools](/guides/omni-tools)).

<CodeGroup>
  ```ts Node theme={null}
  import WebSocket from "ws";
  const ws = new WebSocket(
    "wss://api.pyai.com/v1/omni?format=pcm16&rate=24000",
    [`pyai-key.${process.env.PYAI_API_KEY}`],
  );
  ws.on("open", () => {
    ws.send(JSON.stringify({
      type: "configure",
      voice_id: "stock_dorit_en_us",          // or your cloned / designed voice
      persona: "You are a friendly receptionist.",
      kb_endpoint: "https://your-app.example.com/kb", // grounding (optional)
      tools: [                                // function calling (optional)
        { name: "book_appointment", description: "Book a slot",
          parameters: { type: "object", properties: { time: { type: "string" } } } },
      ],
    }));
  });
  ws.on("message", (d) => console.log(d.toString())); // hello + session_started
  ```

  ```python Python theme={null}
  import os, json, asyncio, websockets

  async def main():
      url = "wss://api.pyai.com/v1/omni?format=pcm16&rate=24000"
      sub = f"pyai-key.{os.environ['PYAI_API_KEY']}"
      async with websockets.connect(url, subprotocols=[sub]) as ws:
          await ws.send(json.dumps({
              "type": "configure",
              "voice_id": "stock_dorit_en_us",
              "persona": "You are a friendly receptionist.",
          }))
          async for frame in ws:
              print(frame)

  asyncio.run(main())
  ```
</CodeGroup>

`session_label` on the connect URL is an **optional** opaque tag echoed to your
own `kb_endpoint` so you can branch per session. When it equals a `/v1/agents`
profile id, the engine loads persona, voice, and greeting from that profile.
Rather not host a knowledge endpoint? Create a **hosted knowledge base** and
bind it to the agent (`/v1/knowledgebases`), and Omni retrieves from it per
turn, nothing for you to run. Full frame catalog: the [Omni wire protocol](/realtime/omni-protocol).

### Speech-to-text (Hear)

One POST transcribes a file:

```bash theme={null}
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](/guides/streaming-stt). For large backlogs, the async
batch API (`POST /v1/transcription/jobs`) is discounted vs. realtime.

### Text-to-speech (Speak)

<CodeGroup>
  ```bash curl theme={null}
  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
  ```

  ```python Python theme={null}
  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)
  ```

  ```ts Node theme={null}
  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
  ```
</CodeGroup>

`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:

```bash theme={null}
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](/guides/amd-answering-machine-detection).

### 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:

```bash theme={null}
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:

```bash theme={null}
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](/guides/trace-guardrails).

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

## Next steps

<CardGroup cols={2}>
  <Card title="Use-case build guides" href="/use-cases/overview">Build your own Gong, a voice dictation app, an AI receptionist, or call-center QA, step by step.</Card>
  <Card title="Build a browser voice agent" href="/guides/browser-voice-agent">Mic → Omni → speakers in \~10 minutes, all client-side.</Card>
  <Card title="Agent greeting messages" href="/guides/agent-greeting">Set an opening line on an agent profile in the console, spoken at turn 0.</Card>
  <Card title="Omni tools & function calling" href="/guides/omni-tools">Give your agent real actions: order lookups, bookings, transfers.</Card>
  <Card title="AMD guide" href="/guides/amd-answering-machine-detection">Twilio Media Streams drop-in, tuning, and webhooks.</Card>
  <Card title="Authentication" href="/authentication">Keys, environments, rotation, revocation.</Card>
  <Card title="Pricing & metering" href="/pricing-and-metering">How usage is measured and billed.</Card>
  <Card title="Errors & limits" href="/errors-and-limits">Error codes, rate limits, idempotency.</Card>
  <Card title="API reference" href="/api-reference">Full request/response schemas, right here in the docs.</Card>
  <Card title="Runnable examples" href="https://github.com/atomsai/pyai-examples">Copy-paste apps, OpenAI drop-in, voice cloning, telephony, call analytics. `npm create pyai-app@latest`.</Card>
</CardGroup>