Integrate via REST & WebSocket

No SDK, no abstractions, just HTTP and WebSocket calls with a Bearer token. Pick this path when you need full control, are working in a language without an SDK, or are wiring Shunya into a low-level pipeline (telephony, embedded, custom runtime).

Your journey

Step 1: Authentication

All requests use Bearer-token authentication. Every HTTP request and WebSocket handshake must include an Authorization header.

Authorization: Bearer <your-api-key>

Generate the key from the dashboard (API Keys → Create New Key). Copy and store it securely, it will not be shown again.

• Never hardcode keys in source, use environment variables or a secrets manager (AWS Secrets Manager, GCP Secret Manager).
• Add .env to .gitignore.
• Rotate immediately if a key is compromised.
• Use separate keys per environment (dev / staging / prod) so you can revoke one without breaking others.

Step 2: Pick your endpoint

Step 3: Make your first request

curl -X POST https://tts.shunyalabs.ai/v1/audio/speech \
  -H "Authorization: Bearer $SHUNYALABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zero-indic",
    "input": "नमस्ते, यह एक परीक्षण है।",
    "voice": "Kavita",
    "language": "hi",
    "response_format": "wav",
    "speed": 1.0,
    "trim_silence": true,
    "volume_normalization": "loudness"
  }' \
  --output output.wav

import requests

resp = requests.post(
    "https://tts.shunyalabs.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "zero-indic",
        "input": "Hello, how are you today?",
        "voice": "Varun",
        "response_format": "mp3",
    },
    timeout=120,
)
resp.raise_for_status()
with open("output.mp3", "wb") as f:
    f.write(resp.content)

# npm install -g wscat
wscat -c "wss://tts.shunyalabs.ai/ws/v1/audio/speech" \
  -H "Authorization: Bearer $SHUNYALABS_API_KEY"

# Send a synthesis request
> {"model": "zero-indic", "input": "Hello!", "voice": "Varun", "response_format": "pcm"}

# Server responds with chunk metadata, binary audio frames, then completion
< {"type": "chunk", "chunk_index": 0, "format": "pcm", "sample_rate": 16000}
< [binary audio bytes]
< {"type": "completion", "total_chunks": 3, "total_duration_seconds": 0.8}

Step 4: Request parameters that matter

Picking a format

• mp3: general storage / delivery, widely supported.
• pcm or wav: real-time pipelines, no decoding overhead.
• mulaw / alaw: telephony (IVR, PSTN), 8 kHz.
• ogg_opus: web streaming, lower latency than MP3.
• flac: lossless archival. Avoid for streaming, full file assembly required.

Step 5: Error handling

Step 6: Ship checklist

• ✅ API key loaded from environment, never source-controlled
• ✅ HTTP client timeout set to ≥120s for long batch synthesis
• ✅ Errors mapped to user-facing messages (401, 429, 5xx)
• ✅ response_format matched to use case (PCM/μ-law for real-time, MP3 for storage)
• ✅ Reconnect + exponential backoff on WebSocket drops
• ✅ GET /health wired into deploy smoke tests
• ✅ X-Request-Id logged for support debugging