Stream Text-to-Speech Audio

Documentation Index

Fetch the complete documentation index at: https://docs.camb.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

How the Streaming Process Works

​

Language Support

​

Coverage by model

​

Choosing a locale

• Use the most specific regional variant available for the accent you want. For example, prefer es-mx over es-es for a Mexican Spanish accent, or zh-cn-sichuan over zh-cn for a Sichuan-flavored Mandarin.
• For best results on the MARS 8.1 beta models, supply a reference voice in the same language and accent as the target locale.
• Codes are case-sensitive lowercase (e.g. pt-br, not pt-BR).

​

Validation behavior

{
  "detail": [{
    "loc": ["body"],
    "msg": "Value error, Language 'zh-tw' is not supported for speech model 'mars-flash'. Allowed languages are: ['en-us', 'en-in', 'zh-cn', ...]"
  }]
}

​

Advanced Customization

• speech_model: Specify the model for synthesis. Available values include mars-8.1-flash-beta, mars-8.1-pro-beta, mars-flash, mars-pro, and mars-instruct.
• Expressive text tags: With mars-instruct, you can also embed delivery tags directly in the text (for example, emotion tags or SSML-style pauses) to shape pacing and tone.
• output_configuration: Set the audio format (wav, mp3), sample rate, and toggle output enhancement.
  • apply_enhancement (boolean, optional): Applies output audio enhancement (loudness, denoising, polish). Defaults to true for most models, false for the speed-oriented mars-flash and mars-8.1-flash-beta models. Set explicitly to override.
• voice_settings: Enhance reference audio quality, maintain the source accent, or adjust the speaking rate.
• inference_options: Adjust stability, temperature, and speaker similarity for unique results.

​

MARS 8.1 Beta Text Controls

​

Pronunciation Control (English)

payload = {
    "text": "He plays the [B EY1 S] guitar while catching a [B AE1 S] fish.",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-8.1-flash-beta"
}

​

Non-verbal Symbols

payload = {
    "text": "[laughter] You really got me. I didn't see that coming at all.",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-8.1-flash-beta"
}

​

Expressive Text Tags (mars-instruct)

• [speaking slowly] You need to understand this. It is very important. We should do this the right way.
• [angry] You need to understand this! It is very important, we should do this the right way!
• [gentle, reassuring] Take a deep breath. You're doing well. Let's go step by step.
• Please pause here <break time="500ms"/> then continue in a calm, clear tone.

​

Tips For Best Results:

• For texts with numbers expand the numbers to words. For example, instead of “123” to “one hundred twenty three” or “one two three” as you need.
• For code-switched sentences, perform transliteration to convert the text to your chosen TTS language. Both of above could be done by a small LLM.
• To adjust pacing or approximate length, use voice_settings.speaking_rate. The streaming TTS endpoint does not support a duration parameter.

​

Output format support by model

​

Example: Real-time Audio Streaming

import requests

payload = {
    "text": "Jupiter, the largest planet in our solar system, is a gas giant with swirling storms like the iconic Great Red Spot.",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-instruct",
    "enhance_named_entities_pronunciation": True,
    "output_configuration": {
        "format": "wav"
    },
    "voice_settings": {
        "enhance_reference_audio_quality": False,
        "maintain_source_accent": False,
        "speaking_rate": 1.0
    },
    "inference_options": {
        "inference_steps": 60,
    }
}

headers = {
    "x-api-key": "your-api-key"
}

response = requests.post(
    "https://client.camb.ai/apis/tts-stream",
    json=payload,
    headers=headers,
    stream=True
)

response.raise_for_status()

with open("output.wav", "wb") as audio_file:
    for chunk in response.iter_content(chunk_size=1024):
        if chunk:
            audio_file.write(chunk)

print("✨ Stream complete. Audio saved to output.wav")

​

SDK Example: Async Streaming

import asyncio
from camb.client import AsyncCambAI, save_async_stream_to_file
from camb.types.stream_tts_output_configuration import StreamTtsOutputConfiguration
from camb.types.stream_tts_voice_settings import StreamTtsVoiceSettings

# Initialize the async client
client = AsyncCambAI(api_key="your-api-key")

async def main():
    # Stream the TTS generation
    response = client.text_to_speech.tts(
        text="Experience high quality realistic sounds with Camb AI.",
        language="en-us",
        speech_model="mars-8.1-flash-beta",
        voice_id=<voice_id>,
        voice_settings=StreamTtsVoiceSettings(
            speaking_rate=1.0
        ),
        output_configuration=StreamTtsOutputConfiguration(
            format="wav"
        )
    )
    
    # Save the stream to a file (or process chunks as they arrive)
    await save_async_stream_to_file(response, "async_stream_output.wav")
    print("Audio stream saved to async_stream_output.wav")

if __name__ == "__main__":
    asyncio.run(main())

​

Streaming vs. Asynchronous: Which to Choose?

{ "format": "wav" }

{
  "enhance_reference_audio_quality": false,
  "maintain_source_accent": false,
  "speaking_rate": 1.5
}