TTS API reference

Every endpoint under ttsv2.shunyalabs.ai, every field, every error code.

export ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIs…paste-here"

export ACCESS_TOKEN=$(curl -s -X POST https://app.shunyalabs.ai/api/auth/token \
  -H "api-key: $SHUNYALABS_API_KEY" | jq -r .token)

Base URLs

Authentication

The same short-lived access token works for both transports — never send your raw API key. Pick the tab for the protocol you're using.

Authorization: Bearer $ACCESS_TOKEN

wss://ttsv2.shunyalabs.ai/v1/realtime?token=$ACCESS_TOKEN

POST /v1/audio/speech

Batch synthesis. Returns audio bytes in the requested format.

Request fields

Response headers

WebSocket /ws

Full protocol in Streaming. Summary below.

Handshake

Three equivalent ways to send the synthesis request on connect, pick whichever fits your client.

wss://ttsv2.shunyalabs.ai/v1/realtime?model=zero-indic&voice=Varun&encoding=pcm

{"type": "config", "model": "zero-indic", "voice": "Varun", "response_format": "pcm"}

{"model": "zero-indic", "input": "Hello!", "voice": "Sunita", "response_format": "pcm"}

Inbound fields

Outbound message shape

For each synthesis, the server emits messages in this order: a chunk metadata JSON, then a binary audio frame, repeated for every chunk; then a final completion JSON. If something goes wrong, an error JSON arrives instead of completion.

1. Chunk metadata (JSON)

Sent before each binary audio frame.

{
  "type": "chunk",
  "request_id": "uuid",
  "chunk_index": 0,
  "is_final": false,
  "format": "pcm",
  "sample_rate": 16000
}

2. Audio data (binary frame)

Raw audio bytes that immediately follow each chunk JSON. In the SDK, isinstance(msg, bytes) is True.

3. Completion (JSON)

Sent once after all audio chunks have been delivered.

{
  "type": "completion",
  "request_id": "uuid",
  "status": "complete",
  "total_chunks": 3,
  "total_duration_seconds": 2.48,
  "format": "pcm",
  "sample_rate": 16000
}

4. Error (JSON)

Sent instead of completion on failure. The connection closes after this message.

{
  "type": "error",
  "request_id": "uuid",
  "error": "Error description"
}

GET /health

Public and unauthenticated — use it for liveness and deployment smoke tests. It also returns the available voices and the default, so it doubles as voice discovery.

Request:

curl https://ttsv2.shunyalabs.ai/health

Response:

{
  "status": "ok",
  "voices": ["Meera", "Varun", "Arjun", "Sunita", "..."],
  "default_voice": "Meera"
}

SDK exception hierarchy

All SDK exceptions inherit from ShunyalabsError.

Rate & concurrency limits

Rate-limit retry pattern

import asyncio
from shunyalabs.exceptions import RateLimitError

async def synthesize_with_backoff(client, text, config, retries=3):
    for attempt in range(retries):
        try:
            return await client.tts.synthesize(text, config=config)
        except RateLimitError:
            wait = 2 ** attempt    # 1s, 2s, 4s
            await asyncio.sleep(wait)
    raise RateLimitError("Max retries exceeded")

Concurrency cap pattern

import asyncio

sem = asyncio.Semaphore(16)

async def safe_synthesize(client, text, config):
    async with sem:
        return await client.tts.synthesize(text, config=config)

tasks = [safe_synthesize(client, s, config) for s in scripts]
results = await asyncio.gather(*tasks)

HTTP error status codes

SDK configuration reference

Self-hosted configuration

client = AsyncShunyaClient(
    api_key="your-api-key",
    tts_url="https://my-tts-server.example.com",
    tts_ws_url="wss://my-tts-server.example.com/ws",
)

GitHub

github.com/Shunyalabsai/shunyalabs-python-sdk