Python SDK

The official Python SDK for Camb.ai provides convenient access to text-to-speech, dubbing, translation, transcription, audio separation, voice cloning, and audio generation. It ships synchronous and asynchronous clients with streaming audio helpers and typed language enums.

Installation

pip install camb-sdk

Requires Python 3.9 or later.

Authentication

Get your API key from Camb.ai Studio and set it as an environment variable. The client reads it via os.getenv("CAMB_API_KEY") so your key never has to appear in source code. The SDK ships two clients. Use CambAI for scripts, data pipelines, and anything thread-managed. Use AsyncCambAI for web servers (FastAPI, Sanic) and high-concurrency applications where blocking would hurt throughput.

import os
from camb.client import CambAI, AsyncCambAI

# Synchronous — for scripts and data pipelines
client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

# Asynchronous — for web servers and high-concurrency applications
async_client = AsyncCambAI(api_key=os.getenv("CAMB_API_KEY"))

Quick Start

The quickest way to get started is streaming TTS audio directly to a file. tts() returns a byte iterator that save_stream_to_file writes in one call:

import os
from camb.client import CambAI, save_stream_to_file

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

stream = client.text_to_speech.tts(
    text="Hello from Camb.ai.",
    language="en-us",
    voice_id=147320,
    speech_model="mars-flash",
)
save_stream_to_file(stream, "output.wav")

For async applications, use AsyncCambAI and save_async_stream_to_file. The interface is identical to the sync client:

import asyncio
import os
from camb.client import AsyncCambAI, save_async_stream_to_file

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

async def main():
    stream = client.text_to_speech.tts(
        text="Hello from Camb.ai.",
        language="en-us",
        voice_id=147320,
        speech_model="mars-flash",
    )
    await save_async_stream_to_file(stream, "output.wav")

asyncio.run(main())

Models

Camb.ai offers MARS models tuned for different quality and latency requirements. Pass the model name as speech_model in any TTS call. If you omit it, the API uses a default model.

Model	Sample Rate	Best For
`mars-8.1-flash-beta`	48 kHz	Faster MARS 8.1 generation; same quality improvements as `mars-8.1-pro-beta`
`mars-8.1-pro-beta`	48 kHz	Improved pronunciation, expressiveness, and prosody over `mars-pro`
`mars-flash`	22.05 kHz	Low-latency real-time applications and conversational AI
`mars-pro`	48 kHz	High-fidelity audio production and long-form content
`mars-instruct`	22.05 kHz	Fine-grained tone and style control via text instructions

MARS Flash
MARS Pro
MARS Instruct

stream = client.text_to_speech.tts(
    text="Hey, I can respond much faster.",
    language="en-us",
    voice_id=147320,
    speech_model="mars-flash",
)

Best for: Voice agents, real-time applicationsSample rate: 22.05 kHz

stream = client.text_to_speech.tts(
    text="High-fidelity audio for production use.",
    language="en-us",
    voice_id=147320,
    speech_model="mars-pro",
)

Best for: Audio production, dubbing, long-form contentSample rate: 48 kHz

stream = client.text_to_speech.tts(
    text="[warm, friendly] Great to meet you!",
    language="en-us",
    voice_id=147320,
    speech_model="mars-instruct",
    user_instructions="Speak warmly and with enthusiasm.",
)

Best for: Fine-grained control over tone and deliverySample rate: 22.05 kHz

TTS Options

The text_to_speech.tts(...) method accepts the core request fields plus optional controls for model behavior and output format.

Option	Type	Description
`text`	string	Text to synthesize. For `mars-instruct`, you can include inline emotion or pacing tags in the text.
`language`	string	BCP-47 locale such as `en-us`.
`voice_id`	integer	Voice profile ID from `list_voices()`.
`speech_model`	string	Model to use, such as `mars-8.1-flash-beta`, `mars-pro`, or `mars-instruct`.
`user_instructions`	string	Adds style, tone, pronunciation, or delivery guidance for the request. Available only with `speech_model="mars-instruct"`.
`output_configuration`	`StreamTtsOutputConfiguration`	Output settings such as audio format.
`voice_settings`	object	Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.
`inference_options`	object	Advanced generation controls for supported models.
`enhance_named_entities_pronunciation`	boolean	Improves pronunciation for names and other named entities when supported.

Example with mars-instruct delivery guidance:

from camb.types import StreamTtsOutputConfiguration

stream = client.text_to_speech.tts(
    text="[warm, friendly] Great to meet you!",
    language="en-us",
    voice_id=147320,
    speech_model="mars-instruct",
    user_instructions="Speak warmly and with enthusiasm.",
    output_configuration=StreamTtsOutputConfiguration(format="wav"),
)

Voices

List Voices

Call list_voices() to retrieve all voices available on your account, including pre-built library voices and any custom voices you have created. The id field is what you pass as voice_id in TTS calls.

import os
from camb.client import CambAI

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

voices = client.voice_cloning.list_voices()
for voice in voices:
    print(f"ID: {voice['id']}  Name: {voice['voice_name']}  Gender: {voice['gender']}")

Create a Custom Voice

To clone a voice, upload a short reference audio sample alongside a name and gender. Setting enhance_audio=True applies preprocessing that improves cloning quality on recordings with background noise.

import os
from camb.client import CambAI

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

with open("reference.wav", "rb") as f:
    result = client.voice_cloning.create_custom_voice(
        voice_name="My Custom Voice",
        gender="female",
        file=f,
        description="Warm and conversational.",
        enhance_audio=True,
    )

print(f"Voice created: {result}")

Language Support

Camb.ai supports up to 312 languages depending on the MARS model — see Language Support for the full per-model locale list. You can pass locale strings directly, but using the Languages enum is recommended because it provides autocomplete in your editor and prevents typos in language codes.

from camb.types.language_enums import Languages

print(Languages.EN_US)   # en-us
print(Languages.HI_IN)   # hi-in
print(Languages.FR_FR)   # fr-fr
print(Languages.DE_DE)   # de-de
print(Languages.JA_JP)   # ja-jp

To fetch the full list of supported languages at runtime, use the languages sub-client. Source languages are what you can transcribe or translate from; target languages are what you can translate or dub into.

import os
from camb.client import CambAI

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

source_languages = client.languages.get_source_languages()
target_languages = client.languages.get_target_languages()

for lang in source_languages:
    print(lang)

Languages supported per model are listed at MARS Models.

Dubbing

The dubbing pipeline takes a publicly accessible video URL, translates the audio track into your target language, and synthesizes speech using a clone of the original speaker’s voice. Dubbing is asynchronous: you submit the job, poll for completion, and then fetch the result.

import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

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

response = client.dub.create_dub(
    video_url="https://example.com/video.mp4",
    source_language=Languages.EN_US,
    target_language=Languages.HI_IN,
)

while True:
    status = client.dub.get_dubbing_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.dub.get_dubbed_run_info(status.run_id)
        print(f"Video: {result.video_url}")
        print(f"Audio: {result.audio_url}")
        break
    time.sleep(5)

To dub into multiple languages in a single job, replace target_language with the target_languages list:

response = client.dub.create_dub(
    video_url="https://example.com/video.mp4",
    source_language=Languages.EN_US,
    target_languages=[Languages.HI_IN, Languages.FR_FR, Languages.DE_DE],
)

Get Transcript

Once a dubbing job completes, you can retrieve the full transcript for any target language using the run_id returned by get_dubbing_status.

transcript = client.dub.get_dubbed_run_transcript(
    run_id=status.run_id,
    language=Languages.HI_IN,
)
print(transcript)

Translation

The translation API accepts a list of text strings and returns them translated into the target language in the same order. Like dubbing, translation is asynchronous. You submit a job and poll until the status reaches SUCCESS.

import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

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

response = client.translation.create_translation(
    texts=["Hello, how are you?", "Welcome to Camb.ai."],
    source_language=Languages.EN_US,
    target_language=Languages.FR_FR,
)

while True:
    status = client.translation.get_translation_task_status(task_id=response["task_id"])
    if status.status == "SUCCESS":
        result = client.translation.get_translation_result(run_id=status.run_id)
        for text in result.texts:
            print(text)
        break
    time.sleep(2)

create_translation accepts a list of strings under texts. All strings are translated in a single job and returned in order.

Transcription

Submit an audio or video file for transcription and retrieve the result once processing completes. You can pass a remote URL via media_url or upload a local file via media_file. The result supports optional word-level timestamps.

import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

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

response = client.transcription.create_transcription(
    language=Languages.EN_US,
    media_url="https://example.com/audio.mp3",
)

while True:
    status = client.transcription.get_transcription_task_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.transcription.get_transcription_result(
            run_id=status.run_id,
            word_level_timestamps=True,
        )
        print(result)
        break
    time.sleep(3)

To transcribe a local file rather than a URL, open it in binary mode and pass it via media_file:

with open("audio.mp3", "rb") as f:
    response = client.transcription.create_transcription(
        language=Languages.EN_US,
        media_file=f,
    )

Audio Separation

Audio separation splits a mixed audio track into its vocal and background components. After the job completes, the result contains separate download URLs for each stem so you can use them independently.

import os
import time
from camb.client import CambAI

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

with open("track.mp3", "rb") as f:
    response = client.audio_separation.create_audio_separation(media_file=f)

while True:
    status = client.audio_separation.get_audio_separation_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.audio_separation.get_audio_separation_run_info(run_id=status.run_id)
        print(result)
        break
    time.sleep(3)

Text-to-Voice

Text-to-Voice creates a brand-new synthetic voice from a written description of the desired vocal characteristics. The API generates several audio samples so you can audition variations before deciding which voice ID to use in production.

import os
import time
from camb.client import CambAI

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

response = client.text_to_voice.create_text_to_voice(
    text="A confident narrator introducing a documentary.",
    voice_description="Deep, measured baritone with a slight gravel. Calm and authoritative.",
)

while True:
    status = client.text_to_voice.get_text_to_voice_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.text_to_voice.get_text_to_voice_result(run_id=status.run_id)
        print(result)
        break
    time.sleep(3)

The result contains multiple sample audio URLs. Preview them and use the voice_id of your preferred sample with client.text_to_speech.tts.

Text-to-Audio

Text-to-Audio generates sound effects or ambient soundscapes from a descriptive text prompt. The job is asynchronous, and the result is a streamable audio file you can save with save_stream_to_file once processing completes.

import os
import time
from camb.client import CambAI, save_stream_to_file

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

response = client.text_to_audio.create_text_to_audio(
    prompt="Heavy rain on a tin roof at night with distant thunder.",
    duration=15,
    audio_type="sound",
)

while True:
    status = client.text_to_audio.get_text_to_audio_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        stream = client.text_to_audio.get_text_to_audio_result(run_id=status.run_id)
        save_stream_to_file(stream, "soundscape.mp3")
        print("Saved to soundscape.mp3")
        break
    time.sleep(3)

Stories

The Stories API takes a document file, structures its content into a narrative, and returns a fully narrated audio output. You can provide a custom narrator voice ID; if omitted, the API selects a default voice appropriate for the source language.

import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

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

with open("story.pdf", "rb") as f:
    response = client.story.create_story(
        file=f,
        source_language=Languages.EN_US,
        title="My Story",
    )

while True:
    status = client.story.get_story_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.story.get_story_run_info(run_id=status.run_id)
        print(result)
        break
    time.sleep(5)

Translated TTS

Translated TTS combines translation and speech synthesis into a single asynchronous job. The text is translated into the target language and then spoken using the voice you specify, without needing to run translation and TTS as separate steps.

import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

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

response = client.translated_tts.create_translated_tts(
    text="Good morning, welcome to our service.",
    voice_id=147320,
    source_language=Languages.EN_US,
    target_language=Languages.HI_IN,
)

while True:
    status = client.translated_tts.get_translated_tts_task_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        print(status)
        break
    time.sleep(3)

Dictionaries

Dictionaries contain custom term mappings that the API applies automatically when running dubbing or translation jobs. They are particularly useful for brand names, product terminology, and proper nouns that need consistent handling across languages.

List Dictionaries

Call get_dictionaries() to retrieve all dictionaries on your account along with their metadata:

import os
from camb.client import CambAI

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

dictionaries = client.dictionaries.get_dictionaries()
for d in dictionaries:
    print(f"{d.id}: {d.name}")

Create from File

Upload a CSV file to create a new dictionary. The file should contain source and target term pairs in a format the API expects:

with open("terms.csv", "rb") as f:
    client.dictionaries.create_dictionary_from_file(
        dictionary_file=f,
        dictionary_name="Product Terms",
        dictionary_description="Brand-specific terminology for our product line.",
    )

Manage Terms

Use add_term_to_dictionary to insert individual term translations and delete_dictionary_term to remove them by ID. Each term takes a source, a target, and the language the target is in:

from camb.types import TermTranslationInput

# Add a term
client.dictionaries.add_term_to_dictionary(
    dictionary_id="dict_123",
    translations=[
        TermTranslationInput(source="Camb.ai", target="कैम्ब.एआई", language="hi-in")
    ],
)

# Delete a term
client.dictionaries.delete_dictionary_term(
    dictionary_id="dict_123",
    term_id="term_456",
)

# Delete the dictionary
client.dictionaries.delete_dictionary(dictionary_id="dict_123")

Custom Provider

If you are running MARS on your own infrastructure through Baseten, you can initialize the client with a provider configuration instead of a Camb.ai API key. See Custom Cloud Providers for deployment instructions.

Baseten

Deploy the MARS model to your Baseten account, then point the client at your deployment URL. Baseten calls require a base64-encoded reference audio sample to be passed with every request:

import base64
import os
from camb.client import CambAI, save_stream_to_file

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

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

stream = client.text_to_speech.tts(
    text="Hello from a self-hosted MARS deployment.",
    language="en-us",
    speech_model="mars-pro",
    request_options={
        "additional_body_parameters": {
            "reference_audio": reference_audio,
            "reference_language": "en-us",
        },
        "timeout_in_seconds": 300,
    },
)
save_stream_to_file(stream, "output.mp3")

Baseten deployments require reference_audio (base64-encoded WAV) and reference_language in additional_body_parameters.

Next Steps

https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5

Voice Agents

Build real-time voice agents with Pipecat

https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f

LiveKit Integration

Create voice agents with LiveKit

API Reference

Explore the full TTS API

Voice Library

Browse available voices

Getting Started

Models

Tutorials

SDK Guides

Hosting Platforms

Integrations

API Reference

Other Products

Release Logs

Installation

Authentication

Quick Start

Models

TTS Options

Voices

List Voices

Create a Custom Voice

Language Support

Dubbing

Get Transcript

Translation

Transcription

Audio Separation

Text-to-Voice

Text-to-Audio

Stories

Translated TTS

Dictionaries

List Dictionaries

Create from File

Manage Terms

Custom Provider

Baseten

Next Steps

Voice Agents

LiveKit Integration

API Reference

Voice Library

Resources

​Installation

​Authentication

​Quick Start

​Models

​TTS Options

​Voices

​List Voices

​Create a Custom Voice

​Language Support

​Dubbing

​Get Transcript

​Translation

​Transcription

​Audio Separation

​Text-to-Voice

​Text-to-Audio

​Stories

​Translated TTS

​Dictionaries

​List Dictionaries

​Create from File

​Manage Terms

​Custom Provider

​Baseten

​Next Steps

Voice Agents

LiveKit Integration

API Reference

Voice Library

​Resources

Installation

Authentication

Quick Start

Models

TTS Options

Voices

List Voices

Create a Custom Voice

Language Support

Dubbing

Get Transcript

Translation

Transcription

Audio Separation

Text-to-Voice

Text-to-Audio

Stories

Translated TTS

Dictionaries

List Dictionaries

Create from File

Manage Terms

Custom Provider

Baseten

Next Steps

Resources