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
Or using yarn:
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
.env file:
CAMB_API_KEY=your_api_key_here
Quick Start
Streaming Text-to-Speech
Generate and stream speech in real-time:
import { CambClient } from '@camb-ai/sdk';
import * as fs from 'fs';
// Initialize the client
const client = new CambClient({
apiKey: process.env.CAMB_API_KEY
});
async function main() {
// Stream TTS audio
const response = await client.textToSpeech.tts({
text: "Hello! Welcome to Camb.ai text-to-speech.",
language: "en-us",
voice_id: 147320,
speech_model: "mars-flash",
output_configuration: {
format: "wav"
}
});
// Process chunks as they arrive
const writeStream = fs.createWriteStream("output.wav");
const reader = response.stream().getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(`Received ${value.length} bytes`);
writeStream.write(value);
}
} finally {
reader.releaseLock();
writeStream.end();
}
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:
MARS Flash
MARS Pro
MARS Instruct
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" }
});
const response = await client.textToSpeech.tts({
text: "High-fidelity audio production.",
language: "en-us",
voice_id: 147320,
speech_model: "mars-pro"
});
const response = await client.textToSpeech.tts({
text: "Great to meet you!",
language: "en-us",
voice_id: 147320,
speech_model: "mars-instruct",
user_instructions: "Speak in a warm, friendly tone",
output_configuration: { format: "wav" }
});
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();
for (const voice of voices) {
console.log(`ID: ${voice.id}, Name: ${voice.voice_name}, Gender: ${voice.gender}`);
}
}
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({
ttsProvider: 'baseten',
providerParams: {
api_key: process.env.BASETEN_API_KEY || 'YOUR_BASETEN_API_KEY',
mars_pro_url: process.env.BASETEN_URL || 'YOUR_BASETEN_MARS_PRO_URL'
}
});
async function main() {
// Read reference audio file
const referenceAudioPath = 'reference.wav';
if (!fs.existsSync(referenceAudioPath)) {
console.error('Reference audio file not found');
return;
}
const referenceAudio = fs.readFileSync(referenceAudioPath).toString('base64');
const response = await client.textToSpeech.tts({
text: 'Hello World and my dear friends',
language: 'en-us',
speech_model: 'mars-pro',
additional_body_parameters: {
reference_audio: referenceAudio,
reference_language: 'en-us'
}
});
await saveStreamToFile(response, 'baseten_output.wav');
console.log('Audio generated with Baseten provider');
}
main();
Next Steps
Resources
