Python SDK

First-party Python package for Shunya Labs. Async client, async generators for streaming, automatic retries, override URLs for self-hosted deployments.

Install

shell

# TTS only
pip install shunyalabs[TTS]

# TTS + ASR + all features
pip install shunyalabs[all]

# Audio playback helpers (sounddevice)
pip install shunyalabs[extras]

Minimum requirements

Python 3.8 or higher.
An active Shunyalabs API key.

Client setup

The client reads SHUNYALABS_API_KEY from the environment by default.

python

from shunyalabs import AsyncShunyaClient
from shunyalabs.tts import TTSConfig

# Option 1, env var (recommended)
client = AsyncShunyaClient()

# Option 2, explicit key
client = AsyncShunyaClient(api_key="your-api-key")

# Option 3, full configuration for production
client = AsyncShunyaClient(
    api_key="your-api-key",
    timeout=120.0,    # seconds before request times out
    max_retries=3,    # retries on 5xx and connection errors
)

# Use as async context manager to ensure connection cleanup
async with AsyncShunyaClient() as client:
    result = await client.tts.synthesize("Hello!", config=config)

Configuration reference

Parameter	Type	Default	Description
`api_key`	string	None	Falls back to `SHUNYALABS_API_KEY` if not set.
`timeout`	float	60.0	Request timeout in seconds.
`max_retries`	int	2	Retries for 5xx and connection failures.
`tts_url`	string	`https://tts.shunyalabs.ai`	Override for self-hosted deployments.
`tts_ws_url`	string	`wss://tts.shunyalabs.ai/ws/v1/audio/speech`	Streaming WebSocket URL override.

Self-hosted / on-premise deployment

python

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",
)

Environment variables

Variable	Description
`SHUNYALABS_API_KEY`	API key for authentication.
`SHUNYALABS_TTS_URL`	Override the TTS batch API base URL.
`SHUNYALABS_TTS_WS_URL`	Override the TTS streaming WebSocket URL.

Error handling

All exceptions inherit from ShunyalabsError in shunyalabs.exceptions.

Exception	HTTP status	Description
`AuthenticationError`	401	Invalid or missing API key.
`PermissionDeniedError`	403	API key lacks required permissions.
`RateLimitError`	429	Rate limit exceeded. Back off and retry.
`SynthesisError`	422	Invalid text or configuration.
`ServerError`	5xx	Transient server error. Safe to retry.
`TimeoutError`	-	Request exceeded configured timeout.
`ConnectionError`	-	Network connectivity failure.

python

from shunyalabs.exceptions import (
    AuthenticationError, RateLimitError,
    SynthesisError, ServerError, ShunyalabsError,
)

try:
    result = await client.tts.synthesize("Hello!", config=config)
except AuthenticationError:
    print("Invalid API key, check SHUNYALABS_API_KEY")
except RateLimitError:
    print("Rate limit hit, back off and retry")
except SynthesisError as e:
    print(f"Synthesis failed: {e}")
except ServerError:
    print("Server error, safe to retry")
except ShunyalabsError as e:
    print(f"SDK error: {e}")

Security best practices

Never hardcode API keys in source code.
Use .env files locally and a secrets manager (AWS Secrets Manager, GCP Secret Manager) in production.
Add .env to .gitignore to prevent accidental commits.
Rotate keys immediately if compromised, generate a new key from the dashboard.

Source & further reading

GitHub: github.com/Shunyalabsai/shunyalabs-python-sdk
Pingala (ASR) PyPI package: pypi.org/project/pingala-shunya

Source: Shunyalabs TTS Developer Documentation v1.0 (March 2026), §1.2 Authentication, §2.5 Error handling, §12.1 Python SDK. Reproduced verbatim.