Skip to main content

โ€‹
Overview

The Camb.ai Python SDK provides a simple interface to integrate high-quality text-to-speech into your applications. This quickstart will have you generating speech in under 5 minutes.

โ€‹
Installation

pip install camb-sdk

โ€‹
Authentication

Get your API key from CAMB.AI Studio and set it as an environment variable: 
export CAMB_API_KEY=your_api_key_here
Or create a .env file: 
CAMB_API_KEY=your_api_key_here

โ€‹
Quick Start

โ€‹
Streaming Text-to-Speech

Generate and stream speech in real-time: 
import os
from camb import CambAI

# Initialize the client
client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

# Stream TTS audio
with open("output.wav", "wb") as f:
    for chunk in client.text_to_speech.tts(
        text="Hello! Welcome to Camb.ai text-to-speech.",
        language="en-us",
        voice_id=147320,
        speech_model="mars-flash",
    ):
        f.write(chunk)

print("Audio saved to output.wav")

โ€‹
Using the Helper Function

The SDK provides a helper to save streams directly: 
import os
from camb import CambAI
from camb.client import save_stream_to_file
from camb.types import StreamTtsOutputConfiguration

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

# Generate and save in one step
stream = client.text_to_speech.tts(
    text="Hello! This is a simple example.",
    language="en-us",
    voice_id=147320,
    output_configuration=StreamTtsOutputConfiguration(
        format="wav"
    ),
)

save_stream_to_file(stream, "output.wav")

โ€‹
Async Client

For web servers and high-concurrency applications, use the async client: 
import asyncio
import os
from camb import AsyncCambAI
from camb.client import save_async_stream_to_file

async def main():
    client = AsyncCambAI(api_key=os.getenv("CAMB_API_KEY"))

    # Stream TTS audio asynchronously
    stream = client.text_to_speech.tts(
        text="Hello from the async client!",
        language="en-us",
        voice_id=147320,
        speech_model="mars-flash",
    )

    await save_async_stream_to_file(stream, "output.pcm")

asyncio.run(main())

โ€‹
Choosing a Model

Camb.ai offers three MARS models optimized for different use cases: 
for chunk in client.text_to_speech.tts(
    text="Fast and efficient speech synthesis.",
    language="en-us",
    voice_id=147320,
    speech_model="mars-flash",
):
    # Process chunk
    pass
Best for: Real-time voice agents, low-latency applicationsSample rate: 22.05kHz

โ€‹
Listing Available Voices

Discover available voices for your application: 
import os
from camb import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

# List all available voices
voices = client.voice_cloning.list_voices()

for voice in voices:
    print(f"ID: {voice.id}, Name: {voice.voice_name}, Gender: {voice.gender}")

โ€‹
Language Support

Camb.ai supports 140+ languages. Specify the language using standard locale codes: Languages supported by each model mentioned at MARS Models. 
# English (US)
client.text_to_speech.tts(text="Hello!", language="en-us", voice_id=147320)

# Spanish
client.text_to_speech.tts(text="Hola!", language="es-es", voice_id=147320)

# French
client.text_to_speech.tts(text="Bonjour!", language="fr-fr", voice_id=147320)

# German
client.text_to_speech.tts(text="Guten Tag!", language="de-de", voice_id=147320)

# Japanese
client.text_to_speech.tts(text="ใ“ใ‚“ใซใกใฏ!", language="ja-jp", voice_id=147320)

โ€‹
Error Handling

Handle common errors gracefully: 
import os
from camb import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

try:
    for chunk in client.text_to_speech.tts(
        text="Hello world!",
        language="en-us",
        voice_id=147320,
    ):
        # Process chunk
        pass
except Exception as e:
    print(f"Error: {e}")

โ€‹
Using Custom Provider

For more details check this guide Custom Cloud Providers

โ€‹
Baseten Deployment

Initialize the client with your API key and the specific model URL. Baseten Provider Example 
from camb.client import CambAI

client = CambAI(
    tts_provider="baseten",
    provider_params={
        "api_key": "YOUR_BASETEN_API_KEY",
        "mars_pro_url": "https://model-xxxxxx.api.baseten.co/environments/production/predict"
    }
)

โ€‹
Usage Example

Passing reference_audio in the additional_body_parameters is required for custom deployments. 
import base64
from camb.client import save_stream_to_file

# Prepare audio reference
with open("reference.wav", "rb") as f:
    ref_audio_b64 = base64.b64encode(f.read()).decode("utf-8")

response = client.text_to_speech.tts(
    text="Generating audio from a private Baseten deployment.",
    language="en-us",
    speech_model="mars-pro",
    request_options={
        "additional_body_parameters": {
            "reference_audio": ref_audio_b64,
            "reference_language": "en-us"
        },
        "timeout_in_seconds": 300
    }
)

save_stream_to_file(response, "baseten_output.mp3")

โ€‹
Next Steps

https://mintcdn.com/cambai/tYKyJM3qUUjDotLB/images/pipecat-orange.svg?fit=max&auto=format&n=tYKyJM3qUUjDotLB&q=85&s=106d962a9b22388180b43a3ab1ddb471

Voice Agents

Build real-time voice agents with Pipecat
https://mintcdn.com/cambai/tYKyJM3qUUjDotLB/images/livekit-orange.svg?fit=max&auto=format&n=tYKyJM3qUUjDotLB&q=85&s=de37de20f6400c15375329e5d941b111

LiveKit Integration

Create voice agents with LiveKit

API Reference

Explore the full TTS API

Voice Library

Browse available voices

โ€‹
Resources