vakyamai 0.1.5

Python SDK for the Vakyam Text-to-Speech API

VakyamAI Python SDK

Python SDK for the Vakyam Text-to-Speech API.

This package intentionally exposes only the public TTS API surface:

• GET /v1/voices
• POST /v1/tts/generate
• POST /v1/tts/stream
• WS /v1/tts/websocket

API-key management and health endpoints are server/dashboard concerns and are not included.

Install

pip install vakyamai

Optional realtime-agent integrations:

pip install "vakyamai[livekit]"
pip install "vakyamai[pipecat]"

Examples

All examples use the production API URL by default. Set your API key first:

export VAKYAM_API_KEY="vak_live_..."

Then run:

python examples/env_key_usage.py
python examples/synthesize.py
python examples/error_handling.py
python examples/async_streaming.py
python examples/async_websocket.py

Available examples:

• env_key_usage.py: create a client from VAKYAM_API_KEY
• synthesize.py: generate an MP3 file from text
• error_handling.py: handle typed SDK/API errors
• async_streaming.py: stream PCM bytes asynchronously
• async_websocket.py: synthesize one sentence over async WebSocket
• livekit_tts.py: construct VakyamTTS for LiveKit Agents
• pipecat_tts.py: construct VakyamTTSService for Pipecat

Initialize

from vakyamai import VakyamAI

Vakyam = VakyamAI(api_key="vak_live_...")

By default, the SDK reads configuration from the environment:

export VAKYAM_API_KEY="vak_live_..."

Then create the client without arguments:

from vakyamai import VakyamAI

Vakyam = VakyamAI()

Precedence:

• api_key= passed in code overrides VAKYAM_API_KEY
• the SDK uses https://api.vakyam.ai by default

VakyamAI uses a 300-second default timeout for non-streaming requests. AsyncVakyamAI uses a 60-second default for streaming connection and initial-response handling.

List Voices

voices = Vakyam.voices.list(group_by="language")
print(voices)

Use the returned voice_name and language code in synthesis requests.

Generate Speech

response = Vakyam.tts.generate(
    text="வணக்கம், நான் வாக்யம் AI பேசுகிறேன்.",
    model_id="raaga-v1",
    voice_name="Archana",
    language="ta-IN",
    output_format="mp3",
    sample_rate=24000,
    speed=1.0,
    voice_strength=50.0,
)

response.save("speech.mp3")
print(response.duration_seconds, response.characters_used)

response.audio contains decoded audio bytes. response.audio_base64 preserves the raw API field. sample_rate accepts 8000, 16000, 24000, or 48000; the default is 24000. voice_strength is a percentage from 0 to 100. It controls how strongly generation follows the selected voice and conditioning. Higher values may improve voice adherence, but can reduce naturalness or introduce artifacts. The recommended default is 50. Supported languages are ta-IN, hi-IN, mr-IN, te-IN, en-IN, gu-IN, bn-IN, and kn-IN. Supported output formats are mp3, wav, pcm, and mulaw.

HTTP Streaming

with open("speech.pcm", "wb") as file:
    for chunk in Vakyam.tts.stream(
        text="வணக்கம்.",
        model_id="raaga-v1",
        voice_name="Archana",
        language="ta-IN",
        output_format="pcm",
        sample_rate=24000,
        voice_strength=50.0,
    ):
        file.write(chunk)

To collect the full stream and response metadata:

streamed = Vakyam.tts.stream_to_bytes(
    text="வணக்கம்.",
    model_id="raaga-v1",
    voice_name="Archana",
    language="ta-IN",
    sample_rate=24000,
    voice_strength=50.0,
)

streamed.save("speech.pcm")
print(streamed.metadata.characters_used)

Async streaming is available through AsyncVakyamAI:

from vakyamai import AsyncVakyamAI

async with AsyncVakyamAI() as Vakyam:
    async for chunk in Vakyam.tts.stream(
        text="வணக்கம்.",
        model_id="raaga-v1",
        voice_name="Archana",
        language="ta-IN",
        output_format="pcm",
        sample_rate=24000,
        voice_strength=50.0,
    ):
        ...

AsyncVakyamAI is intentionally focused on streaming APIs. Use VakyamAI for voices.list() and non-streaming tts.generate().

WebSocket

with Vakyam.tts.websocket(
    model_id="raaga-v1",
    voice_name="Archana",
    language="ta-IN",
    output_format="pcm",
    sample_rate=24000,
    voice_strength=50.0,
) as ws:
    result = ws.synthesize("நான் சரியாக இருக்கிறேன்.")
    result.save("sentence.pcm")

The WebSocket API expects one complete sentence or utterance at a time. Idle WebSocket sessions close after 60 seconds without an incoming message by default. Calling ws.ping() sends a client ping and resets the server idle timer. If result.truncated is true, synthesis stopped early; the returned audio is partial and result.characters_used is 0.

To barge in while audio is streaming, call ws.cancel() (or await ws.cancel()). That sends {"type":"cancel"}, drains until cancellation, and keeps the socket open for the next utterance. The result has cancelled=True and worker-reported characters_used. When synthesize() is already running, invoke cancel() from another thread; for AsyncVakyamAI, invoke it from another task. The synthesis call remains the sole WebSocket receiver and both calls resolve to the same terminal result.

Async WebSocket usage:

from vakyamai import AsyncVakyamAI

async with AsyncVakyamAI() as Vakyam:
    async with Vakyam.tts.websocket(
        model_id="raaga-v1",
        voice_name="Archana",
        language="ta-IN",
        output_format="pcm",
        sample_rate=24000,
        voice_strength=50.0,
    ) as ws:
        result = await ws.synthesize("நான் சரியாக இருக்கிறேன்.")
        result.save("sentence.pcm")

LiveKit Agents

Install the LiveKit extra, then use VakyamTTS in an AgentSession:

pip install "vakyamai[livekit]"

from vakyamai.livekit import VakyamTTS

tts = VakyamTTS(
    voice_name="Archana",
    language="ta-IN",
    model="raaga-v1",
    sample_rate=24000,
)

VakyamTTS streams PCM over Vakyam's WebSocket API and sentence-tokenizes input so each utterance matches the realtime protocol.

Pipecat

Install the Pipecat extra, then add VakyamTTSService to your pipeline:

pip install "vakyamai[pipecat]"

from vakyamai.pipecat import VakyamTTSService

tts = VakyamTTSService(
    settings=VakyamTTSService.Settings(
        voice="Archana",
        model="raaga-v1",
        language="ta-IN",
        speed=1.0,
        voice_strength=50.0,
    ),
    sample_rate=24000,
)

The service keeps a persistent WebSocket and barge-in sends {"type":"cancel"} (no reconnect). Defaults to sentence aggregation to match Vakyam's utterance-oriented API.

Errors

The SDK maps the API error envelope into typed exceptions:

from vakyamai import RateLimitError, ValidationError

try:
    Vakyam.tts.generate(
        text="...",
        model_id="raaga-v1",
        voice_name="Archana",
        language="ta-IN",
        sample_rate=24000,
        voice_strength=50.0,
    )
except RateLimitError as exc:
    print(exc.retry_after_seconds)
except ValidationError as exc:
    print(exc.code, exc.message)

Common exception classes:

• AuthenticationError
• InsufficientCreditsError
• ConcurrencyLimitError
• RateLimitError
• ServiceUnavailableError
• ValidationError
• APIError
• APIConnectionError