Python SDK

Overview

gnani-vachana is the official Python client for the Gnani Speech APIs. It wraps STT and TTS across all three transports — REST, SSE, and WebSocket — so you never hand-roll multipart uploads, SSE frame parsing, WAV headers, or WebSocket lifecycles.

gnani-vachana              ← pip install name
  └── gnani                ← import name
        ├── gnani.stt      → GnaniSTTClient (REST) · GnaniSTTStreamClient (WebSocket)
        └── gnani.tts      → GnaniTTSClient (REST) · GnaniTTSStreamClient (SSE)
                             GnaniTTSRealtimeClient (WebSocket)

The package is dependency-light — requests and websockets only — ships type hints (py.typed), and is maintained by Gnani.ai.

The PyPI package is gnani-vachana, but the Python import package is gnani. Install gnani-vachana, then from gnani.stt import ....

Installation

pip install gnani-vachana

Or with uv:

uv add gnani-vachana

Requirements: Python 3.9+

Authentication

You need a Gnani API key — generate one on the Gnani API platform. A single API key authenticates both STT and TTS; no organization_id or user_id is required. The recommended approach is the GNANI_API_KEY environment variable, which every client reads automatically:

export GNANI_API_KEY="your-api-key"

from gnani.stt import GnaniSTTClient

client = GnaniSTTClient()   # picks up GNANI_API_KEY

Or pass it explicitly:

client = GnaniSTTClient(api_key="your-api-key")

If neither is present, the constructor raises AuthenticationError immediately — before any network call.

If you are upgrading from an SDK version older than 0.7.x, remove the organization_id and user_id constructor arguments. They are no longer accepted.

Choosing a client

Each API has one class per transport. Pick by latency requirement, not by preference — they return the same audio and the same transcripts.

Speech-to-Text

Class	Transport	Use it for
`GnaniSTTClient`	REST — `POST /stt/v3`	Pre-recorded files up to 60 s. Synchronous, one call, one transcript.
`GnaniSTTStreamClient`	WebSocket — `/stt/v3/stream`	Live microphone or telephony audio. Server-side VAD emits a transcript per speech segment. `async`.

Text-to-Speech

Class	Transport	Use it for
`GnaniTTSClient`	REST — `POST /api/v1/tts/inference`	Batch synthesis. Returns the complete audio in one response.
`GnaniTTSStreamClient`	SSE — `POST /api/v1/tts/sse`	Progressive playback with lower time-to-first-audio than REST. Synchronous generator.
`GnaniTTSRealtimeClient`	WebSocket — `/api/v1/tts`	Lowest latency, for conversational agents. `async`.

The two streaming STT/TTS clients are async; the REST and SSE clients are ordinary synchronous Python. You can mix them freely in the same program.

Your first request

Speech-to-Text
Text-to-Speech

from gnani.stt import GnaniSTTClient

client = GnaniSTTClient()

result = client.transcribe("recording.wav", language_code="hi-IN")
print(result["transcript"])

नमस्ते, आप कैसे हैं?

Continue to Speech-to-Text →

from gnani.tts import GnaniTTSClient

client = GnaniTTSClient()

audio = client.synthesize(
    "नमस्ते, आप कैसे हैं?",
    voice="Nalini",
    model="timbre-v2.5",
    language="hi-IN",
    output_file="output.wav",
)

output.wav is written to disk, and the same bytes are returned so you can stream or upload them instead.Continue to Text-to-Speech →

Always pass model="timbre-v2.5" on TTS calls. The SDK still defaults to timbre-v2.0, which the API no longer serves — omitting model returns 400 with The supported models are "timbre-v2.5".

Error handling

Each sub-package defines its own exception hierarchy, rooted at GnaniSTTError and GnaniTTSError. Catching the root class catches everything the SDK raises.

Exception	Raised when
`AuthenticationError`	No API key was passed and `GNANI_API_KEY` is unset.
`APIError`	The API returned a non-200 response. Carries `.status_code` and `.body`.
`InvalidAudioError`	(STT only) The audio file is missing, or its extension is unsupported.
`StreamConnectionError`	The WebSocket connection could not be established.
`StreamClosedError`	An operation was attempted on a closed stream.
`StreamError`	The server sent an error event mid-stream.

from gnani.stt import GnaniSTTClient
from gnani.stt.exceptions import APIError, GnaniSTTError, InvalidAudioError

client = GnaniSTTClient()

try:
    result = client.transcribe("recording.wav", language_code="hi-IN")
except InvalidAudioError as exc:
    print(f"Bad input: {exc}")
except APIError as exc:
    print(f"API returned {exc.status_code}: {exc.body}")
except GnaniSTTError as exc:
    print(f"SDK error: {exc}")

ValueError is raised — before any request leaves your process — for invalid parameter combinations such as an unknown voice, an unsupported sample rate, or speed outside 0.85–1.15.

Request IDs

Every method accepts an optional request_id. When omitted, the SDK generates one and sends it as X-API-Request-ID. It is echoed back in STT REST responses and in TTS WebSocket events.

result = client.transcribe(
    "recording.wav",
    language_code="hi-IN",
    request_id="order-4471-attempt-1",
)

Log it. It is the fastest way for Gnani support to trace a single call end to end.

Pointing at a different environment

All clients take base_url, defaulting to https://api.vachana.ai. The streaming clients derive their WebSocket URL from it automatically (https → wss).

client = GnaniSTTClient(base_url="https://api.vachana.ai")

Speech-to-Text

REST transcription and realtime streaming with the Python SDK.

Text-to-Speech

REST, SSE, and WebSocket synthesis with the Python SDK.

gnani-vachana on PyPI — releases and changelog
STT REST API · STT Realtime API — underlying HTTP reference
TTS REST · TTS SSE · TTS Realtime — underlying HTTP reference
LiveKit Plugin · Pipecat Plugin — framework integrations built on these same APIs

Gnani APIs

APIs

Use Cases

Overview

Installation

Authentication

Choosing a client

Speech-to-Text

Text-to-Speech

Your first request

Error handling

Request IDs

Pointing at a different environment

Further Reading

Speech-to-Text

Text-to-Speech

​Overview

​Installation

​Authentication

​Choosing a client

​Speech-to-Text

​Text-to-Speech

​Your first request

​Error handling

​Request IDs

​Pointing at a different environment

​Further Reading

Speech-to-Text

Text-to-Speech

Overview

Installation

Authentication

Choosing a client

Speech-to-Text

Text-to-Speech

Your first request

Error handling

Request IDs

Pointing at a different environment

Further Reading