Designing a voice

Generate a voice from a text prompt without source audio. The flow has two steps:

Generate a temporary preview. Use the live streaming endpoint for the fastest first audio, or the synchronous endpoint when you want multiple candidates or an encoded response.
Pick the preview you like and call POST /v1/voice-previews/{generated_voice_id}/save to persist a real voice.

Choose model_id from List models and check languages[].language_id for the target language. Preview text can use Audio tags. For guidance on writing voice_description and preview text, see Voice Design prompting.

Stream one preview as it is generated

POST /v1/voice-previews/design/stream returns raw PCM as soon as the first audio chunk is available. The format is fixed to signed 16-bit little-endian PCM at 24 kHz, mono. The endpoint always creates one candidate, so it does not accept preview_count or output_format. The generated-voice-id response header identifies the temporary preview. Wait for a clean end of the response before calling the save endpoint: clean EOF means Breeze has persisted the completed WAV asset. If the connection fails or you stop reading early, discard the partial audio and do not retry by automatically switching to the synchronous endpoint.

import os

from breeze_blue import BreezeBlue, stream

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

with client.voices.stream_design_preview(
    voice_description="A confident young woman with a warm British accent.",
    text="The lighthouse blinked twice and went silent.",
    guidance_scale=4.0,
) as audio:
    generated_voice_id = audio.generated_voice_id
    stream(audio)

print(generated_voice_id)

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

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

const audio = await client.voices.streamDesignPreview({
  voiceDescription: "A confident young woman with a warm British accent.",
  text: "The lighthouse blinked twice and went silent.",
  guidanceScale: 4.0,
});
await stream(audio);

console.log(audio.generatedVoiceId);

curl -N -D preview.headers \
  -X POST "https://api.breeze.blue/v1/voice-previews/design/stream" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "voice_description": "A confident young woman with a warm British accent.",
    "text": "The lighthouse blinked twice and went silent.",
    "guidance_scale": 4.0
  }' | ffplay -autoexit -nodisp -f s16le -ar 24000 -ac 1 -

Generate synchronous previews

Breeze bills by successful preview count times the billable units of the preview text (Chinese, Japanese and Korean characters count as two units each; see Pricing). voice_description and text each accept up to 500 characters. Set preview_count to 3 when you want three candidates in one request. Use guidance_scale to tune how strongly generation follows the voice description and preview script. Accepted values range from 1.0 to 10.0. When you pass it, that exact value is used. When you omit it, Breeze picks a random value between 1.0 and 10.0 for the request.

import os

from breeze_blue import BreezeBlue

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

design = client.voices.create_design_preview(
    voice_description="A confident young woman with a warm British accent.",
    text="The lighthouse blinked twice and went silent.",
    guidance_scale=4.0,
)

for preview in design["previews"]:
    print(preview["generated_voice_id"])

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

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

const design = await client.voices.createDesignPreview({
  voiceDescription: "A confident young woman with a warm British accent.",
  text: "The lighthouse blinked twice and went silent.",
  guidanceScale: 4.0,
});

for (const preview of design.previews) {
  console.log(preview.generatedVoiceId);
}

curl -X POST "https://api.breeze.blue/v1/voice-previews/design" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "voice_description": "A confident young woman with a warm British accent.",
    "text": "The lighthouse blinked twice and went silent.",
    "guidance_scale": 4.0
  }'

Download a completed preview

The synchronous response embeds preview audio in audio_base_64. You can also download any completed preview with GET /v1/voice-previews/{generated_voice_id}/stream. Despite its legacy path name, this GET endpoint downloads an already completed preview; it does not expose generation-time chunks.

Persist the voice

import os

from breeze_blue import BreezeBlue

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

voice = client.voices.save_preview(
    generated_voice_id="gvi_01hpreview",
    voice_name="Lighthouse Keeper",
    voice_description="A confident young woman with a warm British accent.",
    language_code="en",
)

print(voice["voice_id"])

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

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

const voice = await client.voices.savePreview({
  generatedVoiceId: "gvi_01hpreview",
  voiceName: "Lighthouse Keeper",
  voiceDescription: "A confident young woman with a warm British accent.",
  languageCode: "en",
});

console.log(voice.voiceId);

Pass the preview’s language when saving. See supported language codes. language_code is required so the saved voice always carries explicit reference-language metadata.

curl -X POST "https://api.breeze.blue/v1/voice-previews/gvi_01hpreview/save" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "voice_name": "Lighthouse Keeper",
    "voice_description": "A confident young woman with a warm British accent."
  }'

The saved voice works with POST /v1/text-to-speech/{voice_id} and appears on the voices page in the console.

Continue building

Voice Design prompting

Describe a reusable voice identity and write a representative preview script.

Stream a design preview

Start receiving one fixed-format PCM candidate while it is generated.

Create design previews

Inspect voice_description, text, preview_count, and guidance_scale with SDK examples.

Save voice preview

Persist a generated_voice_id as a reusable voice with a name and description.

CLI voice design

Design, audition, and save voice previews from the terminal with breeze voice design.

Voices

Understand designed voices, saved voices, voice IDs, and persisted voice settings.

Text to speech

Use the saved voice_id to generate sync, async, or streaming speech.

Pricing

Estimate preview cost, generation concurrency, and shared Studio/API credits.

Get started

Concepts

Guides

Reference

Stream one preview as it is generated

Generate synchronous previews

Download a completed preview

Persist the voice

Continue building

Voice Design prompting

Stream a design preview

Create design previews

Save voice preview

CLI voice design

Voices

Text to speech

Pricing

​Stream one preview as it is generated

​Generate synchronous previews

​Download a completed preview

​Persist the voice

​Continue building

Voice Design prompting

Stream a design preview

Create design previews

Save voice preview

CLI voice design

Voices

Text to speech

Pricing

Stream one preview as it is generated

Generate synchronous previews

Download a completed preview

Persist the voice

Continue building