pyai-sdk 0.1.1

Official Python SDK for PyAI — speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).

pyai-sdk (Python SDK)

Official Python SDK for PyAI — the voice-AI platform for speech-to-text, text-to-speech, realtime voice agents, and automated call compliance. Zero third-party dependencies (standard library only); Python 3.9+.

PyAI products

• Hear — Speech-to-text tuned for telephony (8 kHz), with streaming partials and a half-price async batch tier; OpenAI-compatible. POST /v1/audio/transcriptions
• Speak — Low-latency streaming text-to-speech (~32–98 ms to first byte) with 36 stock voices and free instant voice cloning. POST /v1/audio/speech
• Omni (flagship) — End-to-end realtime voice agents over a single WebSocket: listens, thinks, and speaks — grounded in your knowledge bases and tools, with natural turn-taking and barge-in. wss://api.pyai.com/v1/omni
• Trace (flagship) — Automated compliance & QA on every call: scores each call against rule packs (TCPA, HIPAA, PII, brand-voice), with findings that cite the rule, auto-redaction, and a tamper-evident audit hash. GET /v1/trace/interactions
• Cue — Turn detection + retrieved knowledge-base context for bring-your-own-LLM/voice pipelines, billed as one per-minute meter. wss://api.pyai.com/v1/audio/transcriptions/stream
• Telephony — Managed US phone numbers routed straight to your Omni agents, no separate carrier contract. POST /v1/telephony/numbers

The contract is https://api.pyai.com/openapi.json. This SDK wraps it with typed errors, automatic retries, and realtime URL helpers.

Install

pip install pyai-sdk

Quickstart

import os
from pyai import PyAI, new_idempotency_key

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

# Text-to-speech
audio = pyai.audio.speech(input="Hello from PyAI.", voice="stock_sarah_style2")
open("hello.wav", "wb").write(audio)

# Voices
voices = pyai.voices.list(gender="female")

# Async transcription (safe retry with an idempotency key)
job = pyai.transcription_jobs.create(
    audio_url="https://example.com/call.wav",
    diarize=True,
    idempotency_key=new_idempotency_key(),
)
done = pyai.transcription_jobs.get(job["job_id"])

Realtime (Omni)

Keys travel as a WebSocket subprotocol. Use the helpers with your preferred WS library (e.g. websockets):

url = pyai.realtime_url(product="omni", agent_id="agent_123")
subprotocol = pyai.realtime_subprotocol()

import asyncio, websockets

async def main():
    async with websockets.connect(url, subprotocols=[subprotocol]) as ws:
        async for frame in ws:
            print(frame)

asyncio.run(main())

Omni uses the native wss://api.pyai.com/v1/omni surface (the default for product="omni"); product="flow" uses /v1/realtime. The older /v2/omni/chat URL is deprecated but still works.

Errors

Failures raise PyAIError with a stable code (branch on it, not the message):

from pyai import PyAIError

try:
    pyai.audio.speech(input="hi")
except PyAIError as err:
    if err.code == "credit_exhausted":
        ...  # out of prepaid credit — add credit or use a sandbox key

Common codes: unauthorized, forbidden, credit_exhausted, rate_limit_exceeded, concurrency_limit_exceeded, idempotency_conflict. 429/5xx are retried automatically (honoring Retry-After); tune with PyAI(api_key, max_retries=...).

Develop

python -m unittest discover -s tests -v   # no network; transport injected