Developer Docs

Build your voice agent in under an hour

WebSocket-based STT and TTS with Python and Node.js SDKs. Request access, receive credentials, start streaming.

Quickstart

From zero to streaming transcript in minutes

1
Install the SDK

Install smallest-ai to add Smallest AI's Python SDK, including STTClient and its asyncio-based streaming methods for real-time speech-to-text.

Terminal
pip install smallest-ai
2
Export your credentials

Use SAI_API_KEY as the SDK credential, request it through early-access by emailing [email protected] or submitting the contact form at the contact page, because keys are manually provisioned rather than a self-service dashboard.

Terminal
export SAI_API_KEY=your_key_here
3
Open a stream and send audio

Open an async WebSocket stream with STTClient, send 16kHz mono PCM audio, and iterate over partial and final transcript tokens from session.receive(), with t.is_final identifying final tokens.

Python
import asyncio, smallest_ai

async def main():
    client = smallest_ai.STTClient()
    async with client.stream() as session:
        await session.send_file("sample.wav")
        async for t in session.receive():
            print(t.text, "final=", t.is_final)

asyncio.run(main())
# API subject to change in early access
SDK Support

Official clients for Python and Node.js

Both SDKs wrap the WebSocket protocol. The REST fallback is also available directly without a client library.

Python SDK
pip install smallest-ai
Async-first client using asyncio. Handles WebSocket lifecycle, reconnects, and backpressure. Python 3.9 and above.
Request access to download
Node.js SDK
npm install smallest-ai
Promise and stream-based API built on the ws library. Works with Node 18+ and Deno via the Deno NPM compat layer.
Request access to download
WebSocket (raw)
wss://api.smallesthq.org/v1/stt
For any language without an official client. JSON handshake, binary audio frames, JSON transcript events. Endpoint subject to change in early access.
Request access for protocol spec
REST Fallback
POST /v1/transcribe
Single-request transcription for batch workloads. Returns a JSON transcript when the full audio has been processed. No streaming.
Request access for endpoint
API Reference

Request and event schema

Simplified reference for early-access partners. Full OpenAPI spec provided on access approval.

WebSocket Handshake (JSON)
{
  "api_key": "your_key",
  "config": {
    "sample_rate": 16000,
    "language": "en",
    "partial_transcripts": true
  }
}
Transcript Event (JSON)
{
  "type": "transcript",
  "text": "call me back tomorrow",
  "is_final": true,
  "latency_ms": 43
}
TTS Request (JSON)
{
  "text": "I will call you back tomorrow afternoon.",
  "voice": "agent-en-1",
  "format": "pcm16",
  "sample_rate": 16000
}
// Server streams PCM audio chunks as binary WebSocket frames
Configuration

Streaming configuration for lowest latency

Audio format and chunk size are the two variables with the largest impact on round-trip time.

Parameter Recommended Notes
Input sample rate 16000 Hz 8000 Hz also accepted (telephone narrowband)
Input encoding PCM 16-bit signed Single channel (mono)
Chunk size 20-40ms Smaller chunks lower latency; larger chunks lower overhead
Partial transcripts true Allows LLM to start before final transcript arrives
Output format (TTS) pcm16 / 16000 Hz Feed directly to a 16kHz PCM audio sink on the call leg
Early Access

Get your API key

We review access requests manually and provision credentials within 1-2 business days. Early access partners also receive direct engineering support.

Request Access