Skip to main content
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.

​
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. 
{
  "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

Streaming

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

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.

API reference

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