Stream Text-to-Speech Audio

Camb AI Python SDK Examples Link To Detailed Models Overview

How the Streaming Process Works

Our streaming service is designed for simplicity and speed. Here’s how it works from request to playback:

Submit Your Text & Configuration

Send a POST request containing your text and desired audio configuration, including the voice, language, and output format.

Receive the Audio Stream

The server immediately begins processing and sends audio data back in chunks over the same connection. Your application can start playing the audio as soon as the first chunk arrives.

Manage Playback & Usage

Continue reading the byte stream until the connection closes, which signals the end of the audio. You can also monitor real-time usage via the X-Credits-Required header included in the response.

Advanced Customization

Fine-tune the audio with additional parameters to control the performance, style, and quality of the generated speech. These are sent in the same JSON payload.

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), and apply enhancements.
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.

The mars-8.1-flash-beta and mars-8.1-pro-beta models do not support the following parameters:

acoustic_quality_boost
temperature
speaker_similarity
maintain_source_accent
stability
output_enhancement
enhance_named_entities_pronunciation
localize_speaker_weight

MARS 8.1 Beta Text Controls

The mars-8.1-flash-beta and mars-8.1-pro-beta models support inline controls for English pronunciation and expressive non-verbal sounds. Add these controls directly in the text field.

Pronunciation Control (English)

Use CMU pronunciation dictionary phonemes in uppercase, wrapped in brackets, to override default English pronunciations.

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

Insert supported tags directly in the text to add expressive non-verbal sounds.

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"
}

Supported tags: [laughter], [sigh], [confirmation], [question], [surprise], [dissatisfaction].

Expressive Text Tags (`mars-instruct`)

You can directly convey expression in the input text by adding short tags for delivery. For a deeper guide to emotion tag intensity, see the Emotion Tag Gradation Guide.

[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.

Keep tags short and place them near the sentence you want to influence.

For comprehensive examples and best practices, see the Emotional Voice Control tutorial.

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

Supported output_configuration.format values depend on the selected speech_model:

Speech Model	Supported output formats
`mars-8.1-flash-beta`	`wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be`
`mars-8.1-pro-beta`	`wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be`
`mars-flash`	`wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be`
`mars-pro`	`wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be`
`mars-instruct`	`wav`, `flac`, `adts`, `pcm_s16le`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be`

Example: Real-time Audio Streaming

This example shows how to call the endpoint and save the incoming audio stream to a file.

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?

Select the right tool for your job by understanding the key differences between our TTS endpoints.

Use Streaming

Ideal for real-time, interactive experiences where immediate audio feedback is crucial.

Use Asynchronous

Perfect for non-real-time tasks, long-form content, or when you need to retrieve a complete audio file later.

Authorizations

x-api-key

string

header

required

The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.

Body

application/json

Streaming Text-to-Speech request parameters.

Request body for /tts-stream.

text

string

required

The text to synthesize into speech (3–3000 characters).

Required string length: 3 - 3000

Example:

"Jupiter, the largest planet in our solar system, is a gas giant with swirling storms."

language

enum<string>

required

BCP-47 locale for the input text (for example, en-us).

Available options:

ro-ro,

nl-nl,

es-es,

zh-tw,

en-uk,

el-gr,

cs-cz,

vi-vn,

bn-bd,

ar-tn,

de-de,

fr-ca,

ar-xa,

th-th,

ar-eg,

ar-sa,

ar-sy,

pa-in,

zh-cn,

ar-jo,

ru-ru,

bn-in,

uk-ua,

es-us,

ja-jp,

ar-ae,

mr-in,

en-au,

de-ch,

pt-pt,

ar-kw,

ar-qa,

as-in,

hi-in,

fr-be,

fi-fi,

fr-fr,

ar-dz,

fr-ch,

it-it,

de-at,

en-in,

ko-kr,

en-us,

zh-hk,

ar-om,

ar-ma,

pl-pl,

ar-ly,

es-mx,

tr-tr,

ar-iq,

ar-lb,

ml-in,

pt-br,

id-id,

ar-bh,

kn-in,

nl-be,

te-in,

ar-ye,

ta-in

Example:

"en-us"

voice_id

integer

required

Voice profile ID to use for synthesis. Get available IDs from /list-voices.

Required range: x >= 1

Example:

147320

speech_model

enum<string>

default:mars-8.1-flash-beta

Speech model variant to use for synthesis.

Available options:

mars-8.1-flash-beta,

mars-8.1-pro-beta,

mars-flash,

mars-pro,

mars-instruct

Example:

"mars-8.1-flash-beta"

enhance_named_entities_pronunciation

boolean

default:false

If true, improves pronunciation of names, brands, and other named entities.

Example:

true

output_configuration

StreamTTSOutputConfiguration · object

Controls output format and enhancement options for the stream.

Hide child attributes

output_configuration.format

enum<string>

default:wav

Audio format for the streamed response. Choose a container (mp3, wav, flac, adts) or a raw PCM format (pcm_*).

Available options:

wav,

flac,

adts,

mp3,

pcm_s16le,

pcm_s16be,

pcm_s32be,

pcm_s32le,

pcm_f32le,

pcm_f32be

Example:

"mp3"

output_configuration.sample_rate

integer | null

Optional sample rate in Hz. Use this to control the audio quality and compatibility with different devices.

Example:

48000

Example:

{ "format": "wav" }

voice_settings

StreamTTSVoiceSettings · object

Voice behavior preferences such as accent preservation and reference enhancement.

Hide child attributes

voice_settings.enhance_reference_audio_quality

boolean | null

default:false

Remove noise from reference audio. (useful when the reference has background noise or compression).

Example:

false

voice_settings.maintain_source_accent

boolean | null

default:false

Maintain the accent from the original source audio.

Example:

false

voice_settings.speaking_rate

number | null

default:1

Controls playback speed for generated speech.

Example:

1.5

Example:

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

inference_options

StreamTTSInferenceOptions · object

Model sampling controls that trade off stability, variation, and latency.

Hide child attributes

inference_options.stability

number | null

Balances voice consistency and audio quality. Lower values keep the voice closer to the original speaker, higher values improve clarity and smoothness—especially useful for weaker reference audio.

Required range: 0 <= x <= 1

Example:

0.6

inference_options.temperature

number | null

Controls randomness. Higher values increase variation and expressiveness.

Required range: 0.01 <= x <= 4

Example:

0.8

inference_options.inference_steps

integer | null

Higher values may improve fidelity at the cost of latency.

Required range: 5 <= x <= 200

Example:

15

inference_options.speaker_similarity

number | null

default:0.7

Adjusts how closely the generated voice matches the original speaker’s voice.

Required range: 0 <= x <= 1

Example:

0.7

inference_options.localize_speaker_weight

number | null

default:0

Controls how much the voice shifts toward a native accent in the target language, at the cost of changing the speaker’s original voice identity slightly.

Required range: 0 <= x <= 1

inference_options.acoustic_quality_boost

boolean | null

Reduce acoustic noise at the cost of slightly worse speaker similarity.

Example:

{
  "stability": 0.6,
  "temperature": 0.8,
  "speaker_similarity": 0.7
}

Response

Streaming audio response

Binary audio stream in WAV format.

Getting Started

Models

SDK Guides

Tutorials

Hosting Platforms

Integrations

API Reference

Release Logs

Stream Text-to-Speech Audio

How the Streaming Process Works

Advanced Customization

MARS 8.1 Beta Text Controls

Pronunciation Control (English)

Non-verbal Symbols

Expressive Text Tags (`mars-instruct`)

Tips For Best Results:

Output format support by model

Example: Real-time Audio Streaming

SDK Example: Async Streaming

Streaming vs. Asynchronous: Which to Choose?

Use Streaming

Use Asynchronous

Authorizations

Body

Response

Getting Started

Models

SDK Guides

Tutorials

Hosting Platforms

Integrations

API Reference

Release Logs

Documentation Index

​How the Streaming Process Works

​Advanced Customization

​MARS 8.1 Beta Text Controls

​Pronunciation Control (English)

​Non-verbal Symbols

​Expressive Text Tags (mars-instruct)

​Tips For Best Results:

​Output format support by model

​Example: Real-time Audio Streaming

​SDK Example: Async Streaming

​Streaming vs. Asynchronous: Which to Choose?

Use Streaming

Use Asynchronous

Authorizations

Body

Response

How the Streaming Process Works

Advanced Customization

MARS 8.1 Beta Text Controls

Pronunciation Control (English)

Non-verbal Symbols

Expressive Text Tags (`mars-instruct`)

Tips For Best Results:

Output format support by model

Example: Real-time Audio Streaming

SDK Example: Async Streaming

Streaming vs. Asynchronous: Which to Choose?