# From a key to working audio

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

Create a key in [PyAI Console](https://console.pyai.com). For a bounded test,
you can also request a sandbox key:

```sh
curl --fail-with-body -sS https://api.pyai.com/v1/sandbox/keys \
  -H 'Content-Type: application/json' \
  -d '{"label":"sdk-quickstart"}'
```

Keep the returned `api_key` private. Sandbox keys expire and have usage and
concurrency limits. Store your key as `PYAI_API_KEY` in a local `.env` file
excluded from Git, or in your deployment's secret store. Never put a live key
in client-side JavaScript or paste it into a coding-agent prompt.

## Make a first call

With `PYAI_API_KEY` exported in your shell, save a speech file:

```sh
curl --fail-with-body -sS https://api.pyai.com/v1/audio/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"pyai-speak","input":"Hello from PyAI.","voice":"stock_emma_en_gb","response_format":"wav"}' \
  -o speech.wav
```

Transcribe a recording you are authorized to process:

```sh
curl --fail-with-body -sS https://api.pyai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -F model=pyai-hear -F file=@speech.wav
```

Omitting the Hear language hint enables automatic detection. Use the
[language support table](https://docs.pyai.com/reference/language-support)
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.

| SDK | Install | Complete project and source |
| --- | --- | --- |
| Python | `pip install pyai-sdk==0.4.0` | [Python](https://pyai.com/sdks/python.md) |
| TypeScript | `npm install @pyai/sdk@0.4.0` | [TypeScript](https://pyai.com/sdks/typescript.md) |
| Twilio | `npm install @pyai/twilio@0.4.2` | [Twilio](https://pyai.com/sdks/twilio.md) |
| LiveKit | `pip install livekit-plugins-pyai==0.1.2` | [LiveKit](https://pyai.com/sdks/livekit.md) |
| Pipecat | `pip install pipecat-pyai==0.1.2` | [Pipecat](https://pyai.com/sdks/pipecat.md) |

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.

## Connect a coding agent

Install Node.js 22+ and your chosen coding agent first. These commands register
PyAI's local stdio MCP server; they do not create a production key.

Claude Code:

```sh
claude mcp add --transport stdio --scope project pyai -- npx -y @pyai/mcp@0.2.0
```

Codex:

```sh
codex mcp add pyai -- npx -y @pyai/mcp@0.2.0
```

Cursor: merge this entry into `.cursor/mcp.json`, preserving existing servers:

```json
{
  "mcpServers": {
    "pyai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pyai/mcp@0.2.0"]
    }
  }
}
```

Open your client's MCP tools view, enable the server if prompted, and ask it to
call `get_started`. For a sandbox test, ask it to call `create_sandbox_key` once
and then `list_voices`. Tool execution follows your coding agent's permissions.

Paste this task into your agent:

```text
Read https://pyai.com/skill.md and https://pyai.com/sdks.md.
Use the starter matching this repository's language/framework to add PyAI voice.
Read the relevant public API guide before coding. Keep credentials in environment
variables. Run a short synthetic audio test and report the result and any missing
credentials. Do not place a phone call or send a message unless I ask for it.
```

## Install the Markdown skill (optional)

Codex, from your project directory:

```sh
mkdir -p .agents/skills/pyai
curl -fSL https://pyai.com/skill.md -o .agents/skills/pyai/SKILL.md
```

Claude Code, from your project directory:

```sh
mkdir -p .claude/skills/pyai
curl -fSL https://pyai.com/skill.md -o .claude/skills/pyai/SKILL.md
```

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](https://developers.openai.com/codex/mcp),
[Codex skills](https://developers.openai.com/codex/skills),
[Cursor MCP](https://cursor.com/docs/mcp), and
[Claude Code MCP](https://code.claude.com/docs/en/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](https://docs.pyai.com/guides/async-transcription-jobs).
For callbacks read [webhooks](https://pyai.com/webhooks.md). Before deployment,
follow [production readiness](https://docs.pyai.com/production-readiness).
The [OpenAPI contract](https://api.pyai.com/openapi.json) and
[documentation index](https://docs.pyai.com/llms.txt) provide the complete API.