Skip to main content
Generate a voice from a text prompt without source audio. The flow has two steps:
  1. Call POST /v1/voice-previews/design with a description and sample script. The request returns one generated_voice_id preview by default.
  2. Pick the preview you like and call POST /v1/voice-previews/{generated_voice_id}/save to persist a real voice.

​
Step 1: Generate previews

Breeze bills by successful preview count times preview text character count. 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
  }'

​
Step 2: Preview the audio

Each preview includes a generated_voice_id. Stream the sample with GET /v1/voice-previews/{generated_voice_id}/stream or decode the audio_base_64 field returned in the design response.

​
Step 3: 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.",
)

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.",
});

console.log(voice.voiceId);

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

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.

Voice clone

Create a voice from source audio when a text prompt is not enough.

Pricing

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