FonadaLabs
Login / Sign Up

Quickstart

Get started with building AI voice agents on Indian telephony infrastructure in minutes.

This guide will walk you through setting up your first voice agent using FonadaLabs' complete voice pipeline — from acquiring Indian phone numbers to deploying conversational AI with ultra-low latency ASR, TTS, and real-time audio processing.

Get Your API Key

Before you begin, you'll need an API key to authenticate your requests. Create Api Key

Using the Text to Speech API

1

Install the SDK

We'll use the fonadalabs library (version 3.0 or later) to interact with our TTS API.

Python
pip install -U fonadalabs
2

Make the API request

Create a new file named example.py and add the following code. Replace YOUR_SHARE_ID with the 8-character share ID shown on any public voice in Voice Arena.

Python
from fonadalabs import TTSClient

client = TTSClient(api_key="YOUR_API_KEY")

# share_id of any public voice in Voice Arena
audio = client.generate_audio(
    "Hello! This is FonadaLabs Text-to-Speech API.",
    share_id="YOUR_SHARE_ID",
    language="English",
    output_file="output.wav",
)
print(f"Generated {len(audio):,} bytes")
3

Execute the code

Python
python example.py

You should see the audio file saved to output.wav and the byte count printed to the console.

4

Stream audio

To start playback before the whole clip is ready, use stream_audio(). It yields audio chunks as Klone V2 Flash generates them. This example also shows how to handle the common errors.

Python
import wave
from fonadalabs import TTSClient, TTSError, CreditsExhaustedError, RateLimitError

client = TTSClient(api_key="YOUR_API_KEY")

try:
    # Klone V2 Flash streams 16-bit PCM, 24 kHz, mono as it is generated
    with wave.open("stream.wav", "wb") as wav:
        wav.setnchannels(1)
        wav.setsampwidth(2)
        wav.setframerate(24000)
        chunks = client.stream_audio(
            "नमस्ते! FonadaLabs Text-to-Speech API में आपका स्वागत है।",
            share_id="YOUR_SHARE_ID",
            language="Hindi",
        )
        for i, chunk in enumerate(chunks, start=1):
            print(f"Chunk {i}: {len(chunk):,} bytes")
            wav.writeframes(chunk)
    print("Saved stream.wav")

except CreditsExhaustedError as e:
    print(f"Credits exhausted. Remaining balance: {e.remaining_balance}")
except RateLimitError as e:
    print(f"Rate limit hit. Retry after {e.retry_after_seconds} seconds")
except TTSError as e:
    print(f"TTS error: {e}")

Streaming is available on Klone V2 Flash only. Chunks are raw 16-bit PCM at 24 kHz, mono, so the example wraps them in a WAV file as they arrive.

Troubleshooting

"Voice names like 'Dhruv' were TTS v1, which has been retired"

Cause: The code passes a voice name with voice=. Named voices belonged to TTS v1, which is retired. generate_audio_ws() was retired with it.

Solution: Pass share_id= with a voice from Voice Arena, and use stream_audio() instead of generate_audio_ws(). Upgrade with pip install -U fonadalabs.

"No community voice found with share_id"

Solution: Check the share ID for typos (it is case-sensitive) and make sure the voice is public or belongs to your account.

Connection Timeout

Problem: Request times out for long texts

Solution: Increase timeout when initializing the client:

client = TTSClient(api_key="YOUR_API_KEY", timeout=600) # 10 minutes

Best Practices

1. Use the right method for your use case

  • • Save a file: Use generate_audio(). It handles long texts too.
  • • Play while generating: Use stream_audio() (Klone V2 Flash).

2. Handle errors gracefully

Always wrap API calls in try-except blocks to handle network issues and API errors.

3. Use async for multiple requests

For generating multiple audio files, run generate_audio_async() calls together with asyncio.gather().