Skip to main content

​
Overview

The Camb.ai TypeScript 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

npm install @camb-ai/sdk
Or using yarn: 
yarn add @camb-ai/sdk
Requires Node.js 18 or higher.

​
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 { CambClient, saveStreamToFile } from '@camb-ai/sdk';

// Initialize the client
const client = new CambClient({
    apiKey: process.env.CAMB_API_KEY
});

async function main() {
    // Generate speech
    const response = await client.textToSpeech.tts({
        text: "Hello! Welcome to Camb.ai text-to-speech.",
        voice_id: 147320,
        language: "en-us",
        speech_model: "mars-flash",
        output_configuration: {
            format: "wav"
        }
    });

    // Save the audio stream to a file
    await saveStreamToFile(response, "output.wav");
    console.log("Audio saved to output.wav");
}

main();

​
Using the Helper Function

For a simpler approach, use the saveStreamToFile helper: 
import { CambClient, saveStreamToFile } from '@camb-ai/sdk';

const client = new CambClient({
    apiKey: process.env.CAMB_API_KEY
});

async function main() {
    const response = await client.textToSpeech.tts({
        text: "Hello! This is a simple example.",
        language: "en-us",
        voice_id: 147320,
        speech_model: "mars-flash",
        output_configuration: {
            format: "wav"
        }
    });

    await saveStreamToFile(response, "output.wav");
    console.log("Audio saved to output.wav");
}

main();

​
Choosing a Model

Camb.ai offers three MARS models optimized for different use cases: 
const response = await client.textToSpeech.tts({
    text: "Fast and efficient speech synthesis.",
    language: "en-us",
    voice_id: 147320,
    speech_model: "mars-flash",
    output_configuration: { format: "wav" }
});
Best for: Real-time voice agents, low-latency applicationsSample rate: 22.05kHz

​
Listing Available Voices

Discover available voices for your application: 
import { CambClient } from '@camb-ai/sdk';

const client = new CambClient({
    apiKey: process.env.CAMB_API_KEY
});

async function main() {
    // List all available voices
    const voices = await client.voiceCloning.listVoices();

    console.log(`Found ${voices.length} voices:`);
    for (const voice of voices.slice(0, 5)) {
        console.log(`  - ID: ${voice.id}, Name: ${voice.voice_name}, Gender: ${voice.gender}, Language: ${voice.language}`);
    }
}

main();

​
Language Support

Camb.ai supports 140+ languages. Specify the language using standard locale codes: Languages supported by each model mentioned at MARS Models. 
const outputConfig = { format: "wav" };

// English (US)
await client.textToSpeech.tts({ text: "Hello!", language: "en-us", voice_id: 147320, output_configuration: outputConfig });

// Spanish
await client.textToSpeech.tts({ text: "Hola!", language: "es-es", voice_id: 147320, output_configuration: outputConfig });

// French
await client.textToSpeech.tts({ text: "Bonjour!", language: "fr-fr", voice_id: 147320, output_configuration: outputConfig });

// German
await client.textToSpeech.tts({ text: "Guten Tag!", language: "de-de", voice_id: 147320, output_configuration: outputConfig });

// Japanese
await client.textToSpeech.tts({ text: "こんにちは!", language: "ja-jp", voice_id: 147320, output_configuration: outputConfig });

​
Error Handling

Handle common errors gracefully: 
import { CambClient, saveStreamToFile } from '@camb-ai/sdk';

const client = new CambClient({
    apiKey: process.env.CAMB_API_KEY
});

async function main() {
    try {
        const response = await client.textToSpeech.tts({
            text: "Hello world!",
            language: "en-us",
            voice_id: 147320,
            output_configuration: { format: "wav" }
        });

        await saveStreamToFile(response, "output.wav");
    } catch (error) {
        console.error(`Error: ${error.message}`);
        if (error.body) {
            console.error("Details:", error.body);
        }
    }
}

main();

​
Using Custom Provider

For more details check this guide Custom Cloud Providers

​
Baseten Deployment

Use your own Baseten deployment for one-shot voice cloning. Provide a reference_audio sample of the voice you want to clone. Full example 
import { CambClient, saveStreamToFile } from '@camb-ai/sdk';
import * as fs from 'fs';

// Initialize client with Baseten provider
const client = new CambClient({
    apiKey: process.env.CAMB_API_KEY,
    ttsProvider: 'baseten',
    providerParams: {
        api_key: process.env.BASETEN_API_KEY,
        mars_pro_url: process.env.BASETEN_URL
    }
});

async function main() {
    try {
        // Read reference audio file (you need to provide this)
        const referenceAudioPath = process.env.REFERENCE_AUDIO_PATH || 'reference.wav';

        if (!fs.existsSync(referenceAudioPath)) {
            console.error(`Reference audio file not found: ${referenceAudioPath}`);
            console.log('Please provide a reference audio file or set REFERENCE_AUDIO_PATH environment variable');
            return;
        }

        const referenceAudio = fs.readFileSync(referenceAudioPath).toString('base64');

        console.log('Generating speech with Baseten provider...');
        const response = await client.textToSpeech.tts({
            text: 'Hello World and my dear friends',
            language: "en-us",
            speech_model: "mars-flash",
            voice_id: 1, // Required but ignored when using custom hosting provider
            additional_body_parameters: {
                reference_audio: referenceAudio,
                reference_language: "en-us"
            }
        });

        const outputFile = 'baseten_output.wav';
        await saveStreamToFile(response, outputFile);
        console.log(`✓ Audio generated with Baseten provider and saved to ${outputFile}`);

    } catch (error) {
        console.error('Error:', error.message);
        if (error.body) {
            console.error('Details:', error.body);
        }
    }
}

main();

​
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

​
Resources