Text to speech
Covers one-shot requests, batching multiple lines, and per-call voice settings.
Single request
python
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_xeh3w54cqvnp",
text="Hello, world.",
output_format="mp3",
)
save(audio, Path("hello.mp3"))
typescript
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_xeh3w54cqvnp",
{ text: "Hello, world." },
{ outputFormat: "mp3" },
);
await save(audio, "hello.mp3");
curl
curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp?output_format=mp3" \
-H "xi-api-key: $BREEZE_API_KEY" \
-H "content-type: application/json" \
-d '{ "text": "Hello, world." }' \
--output hello.mp3
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_xeh3w54cqvnp",
text="Hello, world.",
output_format="mp3",
)
save(audio, Path("hello.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
Pass voice_settings to override voice defaults per call. guidance_scale adjusts how strongly generation follows the prompt and reference voice.
json
{
"text": "...",
"voice_settings": {
"guidance_scale": 4.0
}
}
{
"text": "...",
"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.
python
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_xeh3w54cqvnp",
text="Render this longer script.",
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"))
typescript
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_xeh3w54cqvnp",
{ text: "Render this longer script." },
{ 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
curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp?delivery=async&output_format=mp3" \
-H "xi-api-key: $BREEZE_API_KEY" \
-H "content-type: application/json" \
-d '{ "text": "Render this longer script." }'
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_xeh3w54cqvnp",
text="Render this longer script.",
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"))Inspecting the result
The logs page shows inline playback, a download link, and "Copy as cURL".