SDK quickstart

Install the SDK, create a Developer Console API key, and synthesize your first audio in under a minute.

1. Create an API key

Open the API keys page, select Create API key, name it, and copy the secret once. Treat BREEZE_API_KEY like a password.

2. Install the SDK

Python:

# uv
uv add breeze-blue

# pip
pip install breeze-blue

TypeScript:

# pnpm
pnpm add @breeze.blue/sdk

# npm
npm install @breeze.blue/sdk

# yarn
yarn add @breeze.blue/sdk

3. Set environment variables

export BREEZE_API_KEY="brz_..."

4. Convert text to speech

Python uses snake_case. TypeScript uses camelCase.

import os
from pathlib import Path

from breeze_blue import BreezeBlue, play, save

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

audio = client.text_to_speech.convert(
    voice_id="voc_xeh3w54cqvnp",
    text="Hello from Breeze. Your SDK is ready.",
    output_format="mp3",
)

play(audio)
save(audio, Path("hello.mp3"))

import { BreezeBlueClient } from "@breeze.blue/sdk";
import { play, 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 from Breeze. Your SDK is ready." },
  { outputFormat: "mp3" },
);

await play(audio);
await save(audio, "hello.mp3");

5. Stream audio

Use streaming when playback should begin before the full response has been generated.

import os

from breeze_blue import BreezeBlue, stream

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

audio_stream = client.text_to_speech.stream(
    voice_id="voc_xeh3w54cqvnp",
    text="Streaming starts as soon as audio is available.",
)

stream(audio_stream)

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

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

const audioStream = await client.textToSpeech.stream(
  "voc_xeh3w54cqvnp",
  { text: "Streaming starts as soon as audio is available." },
);

await stream(audioStream);

Streaming responses default to pcm to reduce time to first audio. Pass output_format="wav" / { outputFormat: "wav" } or mp3 when you want that wire format explicitly.

6. Realtime conversation audio

Use realtime text to speech when one connection should handle multiple conversation turns. Realtime audio is fixed to pcm_s16le, 24000 Hz, mono, 16-bit. Start consuming before appending text: audio can arrive after flush() and may continue after the turn ends, so keep consuming until turn.done.

import asyncio
import os

from breeze_blue import BreezeBlue, stream

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


async def consume_audio(connection) -> tuple[bytes, dict]:
    audio = bytearray()
    audio_format = None
    async for event in connection:
        if event["type"] == "session.ready":
            audio_format = event["audio_format"]
        elif event["type"] == "audio":
            audio.extend(event["audio"])
        elif event["type"] == "error":
            raise RuntimeError(event.get("message"))
        elif event["type"] == "turn.cancelled":
            raise RuntimeError(f"Turn cancelled: {event['turn_id']}")
        elif event["type"] == "turn.done":
            if audio_format is None:
                raise RuntimeError("Missing realtime audio format")
            return bytes(audio), audio_format
    raise RuntimeError("Realtime session closed before turn.done")


async def speak() -> None:
    async with client.text_to_speech.connect_realtime(
        voice_id="voc_xeh3w54cqvnp",
        model_id="breeze-tts-2",
    ) as connection:
        consumer = asyncio.create_task(consume_audio(connection))
        await connection.start_turn("turn_1")
        await connection.append_text("Hello from Breeze.")
        await connection.flush()
        await connection.end_turn()
        audio, audio_format = await consumer

    stream(audio, audio_format=audio_format)


asyncio.run(speak())

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

const pcmChunks: Uint8Array[] = [];
const consumer = (async () => {
  for await (const message of connection) {
    if (message.type === "audio") {
      pcmChunks.push(message.audio);
    } else if (message.type === "error") {
      throw new Error(`Realtime TTS failed: ${message.code}: ${message.message}`);
    } else if (message.type === "turn.cancelled") {
      throw new Error(`Turn cancelled: ${message.turnId}`);
    } else if (message.type === "turn.done") {
      return;
    }
  }
  throw new Error("Realtime session closed before turn.done");
})();

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

await consumer;
connection.close();

See the realtime guide for the full event protocol, keepalive pings, browser client_secret sessions, and error handling.

7. List voices and history

Use voices to choose saved or public voices, and history to inspect previous text-to-speech generations.

import os

from breeze_blue import BreezeBlue

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

voices = client.voices.search()
first_voice = voices["voices"][0]

items = client.history.list()
latest = items["history"][0]

print(first_voice["voice_id"], first_voice["name"])
print(latest["history_item_id"], latest["text"])

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

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

const voices = await client.voices.search();
const firstVoice = voices.voices[0];

const items = await client.history.list();
const latest = items.history[0];

console.log(firstVoice.voiceId, firstVoice.name);
console.log(latest.historyItemId, latest.text);

8. Inspect the request

The logs page shows the call with status, latency, audio download, and Copy as cURL.

Next steps

Text to speech guide

Add batching, async jobs, expressive instructions, and per-call voice settings.

Convert text to speech

Inspect every request field, response body, and SDK example for the endpoint you just called.

Streaming

Start playback before the full response has been generated.

Realtime text to speech

Keep one WebSocket open for multi-turn conversation audio.

Output formats

Choose MP3, WAV, FLAC, PCM, AAC, or Opus for your playback and pipeline needs.

Rate limits

Plan retries, async jobs, and concurrency around Breeze generation limits.

Get started

Concepts

Guides

Reference

1. Create an API key

2. Install the SDK

3. Set environment variables

4. Convert text to speech

5. Stream audio

6. Realtime conversation audio

7. List voices and history

8. Inspect the request

Next steps

Text to speech guide

Convert text to speech

Streaming

Realtime text to speech

Output formats

Rate limits

​1. Create an API key

​2. Install the SDK

​3. Set environment variables

​4. Convert text to speech

​5. Stream audio

​6. Realtime conversation audio

​7. List voices and history

​8. Inspect the request

​Next steps

Text to speech guide

Convert text to speech

Streaming

Realtime text to speech

Output formats

Rate limits

1. Create an API key

2. Install the SDK

3. Set environment variables

4. Convert text to speech

5. Stream audio

6. Realtime conversation audio

7. List voices and history

8. Inspect the request

Next steps