> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Text-to-Speech (REST)

> Synchronous text-to-speech with full audio returned in one response.

<Info>
  **Currently in beta.** You're on the priority waitlist and among the first to get access.
</Info>

## Overview

Get the complete synthesized audio in one response. Best for downloads or batch processing. For streaming playback, see [TTS Streaming](/vachana/TTS/tts-sse) or [TTS Realtime](/vachana/TTS/tts-websocket).

<Note>
  Passing numbers, IDs, dates, or currency as raw strings causes mispronunciations. See the [Input Formatting Guide](/vachana/TTS/tts-input-formating) for correct formatting of phone numbers, account numbers, PINs, Aadhaar, vehicle registration numbers, GSTIN, currency, and more.
</Note>

***

## Available Voices

| Voice   | Gender | Description              |
| ------- | ------ | ------------------------ |
| Pranav  | Male   | Bold, Trustworthy        |
| Kaveri  | Female | Confident, Bright        |
| Shubhra | Female | Gentle, Expressive       |
| Deepak  | Male   | Grounded, Conversational |

***

## Python SDK

The official Python SDK lets you synthesize speech in one line, without constructing JSON payloads or handling binary audio responses manually.

### Installation

```bash theme={null}
pip install gnani-vachana
```

Requires **Python 3.9+**.

### Authentication

The TTS client requires only your API key.

<CodeGroup>
  ```python Constructor argument theme={null}
  from gnani.tts import GnaniTTSClient

  client = GnaniTTSClient(api_key="your-api-key")
  ```

  ```bash Environment variable theme={null}
  export GNANI_API_KEY="your-api-key"
  ```

  ```python Environment variable (usage) theme={null}
  from gnani.tts import GnaniTTSClient

  # Picks up GNANI_API_KEY automatically
  client = GnaniTTSClient()
  ```
</CodeGroup>

### Synthesize Speech

The `synthesize` method returns the complete audio as bytes, which you can write to a file or pass directly to an audio player.

```python theme={null}
from gnani.tts import GnaniTTSClient

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

audio = client.synthesize(
    "नमस्ते, आप कैसे हैं?",
    voice="sia",
)

with open("output.wav", "wb") as f:
    f.write(audio)
```

### Custom Audio Config

Control the sample rate, encoding, and container format of the output audio.

```python theme={null}
from gnani.tts import GnaniTTSClient, AudioConfig

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

audio = client.synthesize(
    "यह एक टेस्ट है",
    voice="raju",
    audio_config=AudioConfig(
        sample_rate=44100,
        encoding="linear_pcm",
        container="wav",
    ),
)

with open("output.wav", "wb") as f:
    f.write(audio)
```

### List Available Voices

```python theme={null}
from gnani.tts import GnaniTTSClient

voices = GnaniTTSClient.supported_voices()
print(voices)
```

## Supported Languages

The Gnani Timbre v2.0 API supports 2 languages.

| Language | Native Script       | Example                    |
| -------- | ------------------- | -------------------------- |
| English  | Latin               | "I am going to the market" |
| Hindi    | Devanagari (हिन्दी) | "मैं बाज़ार जा रहा हूँ"    |


## OpenAPI

````yaml POST /api/v1/tts/inference
openapi: 3.1.0
info:
  title: TTS Server
  description: Text-to-Speech API with WebSocket, SSE and gRPC streaming support
  version: 1.0.0
servers:
  - url: https://api.vachana.ai
    description: Production server
security: []
paths:
  /api/v1/tts/inference:
    post:
      summary: TTS Inference
      operationId: tts_inference_api_v1_tts_inference_post
      parameters:
        - name: X-API-Key-ID
          in: header
          required: true
          schema:
            anyOf:
              - type: string
            title: X-Api-Key-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
      responses:
        '200':
          description: Successful audio synthesis
          content:
            audio/wav:
              schema:
                type: string
                format: binary
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/ogg:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                success: false
                error:
                  type: INVALID_REQUEST_ERROR
                  message: Invalid text or audio configuration.
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                success: false
                error:
                  type: RATE_LIMIT_ERROR
                  message: Rate limit exceeded. Please try again later.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                success: false
                error:
                  type: API_ERROR
                  message: An unexpected error occurred while processing.
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                success: false
                error:
                  type: SERVICE_UNAVAILABLE
                  message: Text-to-speech service is temporarily unavailable.
components:
  schemas:
    TextToSpeechRequest:
      properties:
        text:
          type: string
          title: Text
        voice:
          type: string
          title: Voice
          description: ID of a pre-defined voice. Ignored if speaker_embedding is provided.
          enum:
            - Karan
            - Simran
            - Nara
            - Riya
            - Viraj
            - Raju
        model:
          allOf:
            - $ref: '#/components/schemas/TTSModel'
        audio_config:
          allOf:
            - $ref: '#/components/schemas/AudioConfig'
      type: object
      required:
        - text
        - model
        - audio_config
      title: TextToSpeechRequest
      description: Request body for TTS inference.
      example:
        audio_config:
          bitrate: 192k
          container: mp3
          encoding: linear_pcm
          num_channels: 1
          sample_rate: 44100
          sample_width: 2
        language: IND-IN
        model: vachana-voice-v3
        text: नमस्ते, आप कैसे हैं?
        voice: Karan
    StandardErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
    TTSModel:
      type: string
      enum:
        - vachana-voice-v3
      title: TTSModel
      description: Supported TTS models.
    AudioConfig:
      properties:
        sample_rate:
          type: integer
          maximum: 44100
          minimum: 8000
          title: Sample Rate
          description: Sample rate in Hz
        num_channels:
          type: integer
          maximum: 8
          minimum: 1
          title: Num Channels
          description: Number of audio channels
        sample_width:
          type: integer
          maximum: 4
          minimum: 1
          title: Sample Width
          description: Sample width in bytes
        encoding:
          allOf:
            - $ref: '#/components/schemas/AudioEncoding'
          description: Audio encoding format
        container:
          allOf:
            - $ref: '#/components/schemas/AudioContainer'
          description: Audio container format
        bitrate:
          allOf:
            - $ref: '#/components/schemas/MP3Bitrate'
          description: MP3 bitrate (only used when container=mp3)
      type: object
      title: AudioConfig
      description: Audio output configuration.
    ErrorDetail:
      type: object
      properties:
        type:
          type: string
          description: A short error code string (e.g., 'INVALID_REQUEST_ERROR').
        message:
          type: string
          description: A descriptive error message.
    AudioEncoding:
      type: string
      enum:
        - linear_pcm
        - oggopus
      title: AudioEncoding
      description: Supported audio encodings.
    AudioContainer:
      type: string
      enum:
        - raw
        - mp3
        - wav
        - mulaw
        - ogg
      title: AudioContainer
      description: Supported audio containers.
    MP3Bitrate:
      type: string
      enum:
        - 96k
        - 128k
        - 192k
      title: MP3Bitrate
      description: Supported MP3 bitrate options (only used when container is MP3).

````