Text to speech

Use text to speech for short previews, dialogue lines, and production audio generation.

Single request

import os
from pathlib import Path

from breeze_blue import BreezeBlue, save

client = BreezeBlue(api_key=os.environ["BREEZE_API_KEY"])

audio = client.text_to_speech.convert(
    voice_id="voc_8rsb3nhb7645",
    text="I can't believe you brought him here!",
    output_format="mp3",
)

save(audio, Path("surprise.mp3"))

import { BreezeBlueClient } from "@breeze.blue/sdk";
import { save } from "@breeze.blue/sdk/node";

const client = new BreezeBlueClient({
  apiKey: process.env.BREEZE_API_KEY!,
});

const audio = await client.textToSpeech.convert(
  "voc_8rsb3nhb7645",
  { text: "I can't believe you brought him here!" },
  { outputFormat: "mp3" },
);

await save(audio, "surprise.mp3");

curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_8rsb3nhb7645?output_format=mp3" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "text": "I can'\''t believe you brought him here!" }' \
  --output surprise.mp3

Batching multiple lines

For dialogue, send one request per line and concatenate the audio. This keeps responses small, allows parallel calls, and limits retries to failed segments. Use async jobs or HTTP streaming when you already have complete text for each line. Use realtime WebSocket when your product is generating and speaking turns during a live conversation.

Realtime conversation

Realtime text to speech keeps one WebSocket connection open across multiple turns. It is optimized for voice agents, live chat, and barge-in flows where avoiding a new HTTP connection per turn matters.

const connection = await client.textToSpeech.realtime.connect(
  "voc_8rsb3nhb7645",
  { modelId: "breeze-tts-2" },
);

connection.startTurn("turn_1");
connection.appendText("Hello from Breeze.");
connection.flush();
connection.endTurn();

Realtime audio is fixed to pcm_s16le, 24000 Hz, mono, 16-bit. It does not accept output_format; request mp3 or wav from the HTTP endpoints when you need encoded files.

Tuning expressive controls

Combine instructions with voice_settings to control delivery per call. guidance_scale adjusts how strongly generation follows those instructions and the reference voice. The accepted range is 1.0 to 10.0. Write instructions in Chinese for Chinese TTS. For English and every other speech language, including Japanese, Korean, Spanish, and French, write instructions in English. The API, SDKs, CLI, and realtime WebSocket do not translate TTS instructions automatically, which keeps high-volume generation latency predictable. The Instruction Enhance endpoint improves an instruction in the same language you supplied; it does not translate it for inference.

{
  "text": "I can't believe you brought him here!",
  "instructions": "Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.",
  "voice_settings": {
    "guidance_scale": 4.0
  }
}

Async jobs

Keep sync and streaming calls for short previews. Use async jobs for long text, reference-heavy voices, or batch production so the caller can poll status and download the audio after generation completes.

import os
from pathlib import Path

from breeze_blue import BreezeBlue, save

client = BreezeBlue(api_key=os.environ["BREEZE_API_KEY"])

job = client.text_to_speech.create_job(
    voice_id="voc_8rsb3nhb7645",
    text="I can't believe you brought him here!",
    output_format="mp3",
)

status = client.generation_jobs.get(job["generation_job_id"])
if status["status"] == "ready":
    audio = client.generation_jobs.download_audio(job["generation_job_id"])
    save(audio, Path("async.mp3"))

import { BreezeBlueClient } from "@breeze.blue/sdk";
import { save } from "@breeze.blue/sdk/node";

const client = new BreezeBlueClient({
  apiKey: process.env.BREEZE_API_KEY!,
});

const job = await client.textToSpeech.createJob(
  "voc_8rsb3nhb7645",
  { text: "I can't believe you brought him here!" },
  { outputFormat: "mp3" },
);

const status = await client.generationJobs.get(job.generationJobId);
if (status.status === "ready") {
  const audio = await client.generationJobs.downloadAudio(job.generationJobId);
  await save(audio, "async.mp3");
}

curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_8rsb3nhb7645?delivery=async&output_format=mp3" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "text": "I can'\''t believe you brought him here!" }'

Inspecting the result

The logs page shows inline playback, a download link, and Copy as cURL.

Continue building

Convert text to speech

Inspect request fields, SDK examples, response bodies, and generated errors.

CLI text to speech

Generate, stream, and save speech from the terminal with breeze tts.

Streaming

Use the streaming endpoint when playback should begin before the full response is ready.

Realtime text to speech

Keep one WebSocket open across live conversation turns.

Output formats

Pick an encoding for browser playback, post-processing, or low-latency audio pipelines.

Managing history

List previous generations, download audio, and delete test runs.

Get started

Concepts

Guides

Reference

Single request

Batching multiple lines

Realtime conversation

Tuning expressive controls

Async jobs

Inspecting the result

Continue building

Convert text to speech

CLI text to speech

Streaming

Realtime text to speech

Output formats

Managing history

​Single request

​Batching multiple lines

​Realtime conversation

​Tuning expressive controls

​Async jobs

​Inspecting the result

​Continue building

Convert text to speech

CLI text to speech

Streaming

Realtime text to speech

Output formats

Managing history

Single request

Batching multiple lines

Realtime conversation

Tuning expressive controls

Async jobs

Inspecting the result

Continue building