SDKs

Official SDKs wrap the same public contract as https://api.pyai.com/openapi.json. They handle bearer auth, retries on 429 and 5xx, multipart uploads, and idempotency helpers. Raw curl and WebSocket examples in these docs stay valid; use the SDK when you want that plumbing done for you.

pip install pyai-sdk

npm install @pyai/sdk

import os
from pyai import PyAI

pyai = PyAI(api_key=os.environ["PYAI_API_KEY"])

import PyAI from "@pyai/sdk";

const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });

Set PYAI_API_KEY from the quickstart. Treat the key as an opaque string. Do not parse or decode it.

What each client covers

Job	Python (`pyai-sdk`)	TypeScript (`@pyai/sdk`)
One-file Hear	`pyai.audio.transcriptions.create(...)`	`pyai.audio.transcriptions.create({ file })`
Speak	`pyai.audio.speech(...)` returns bytes	`pyai.audio.speech(...)` returns bytes; `speechStream` for first-byte playback
Hear stream	URL helper + your WebSocket	`pyai.audio.transcriptions.stream()`
Clone	`pyai.clones.create` / `get` / `list` / `delete`	`pyai.clones.create` / `get` / `list` / `delete`
Identity	`GET /v1/me` via HTTP	`pyai.me()`
Omni	URL helper; send frames yourself	`omni.connect()` hides the `type` vs `event` frame-key split

clones.get filters GET /v1/voice/clones. The API has no GET-by-id for clones.

When to stay on curl or a raw socket

You are proving a key in 30 seconds: POST /v1/sandbox/keys then GET /v1/me.
You are integrating a language the official SDKs do not cover.
You need the exact Omni binary frames (0x01 audio, 0x02 transcript, 0x03 control). The Omni protocol is the contract.

Framework adapters

Keep LiveKit or Pipecat if those products already own the loop. PyAI is the speech layer only. Those packages do not create or select an Omni agent.

Adapter	Install	Guide
LiveKit Agents (Python)	`pip install livekit-plugins-pyai==0.1.0`	LiveKit
Pipecat (Python)	`pip install pipecat-pyai==0.1.0`	Pipecat

AI coding agents

The PyAI MCP server can mint a sandbox key and call Hear, Speak, and the voice catalog as tools. See Use PyAI in Cursor.

Quickstart

Mint a key and copy a first call in curl, Python, or Node.

Errors and limits

Stable codes, first-call failures, and when not to retry.

Get started

Agents

Speech To Text (Hear)

Text To Speech (Speak)

Clone

Cast

Dub

Calls & intelligence

Frameworks

Integrations

Use cases

Reference

What each client covers

When to stay on curl or a raw socket

Framework adapters

AI coding agents

Quickstart

Errors and limits

​What each client covers

​When to stay on curl or a raw socket

​Framework adapters

​AI coding agents

Quickstart

Errors and limits

What each client covers

When to stay on curl or a raw socket

Framework adapters

AI coding agents