> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breezeblue.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Designing a voice

> Generate a voice from a text prompt.

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.

```python theme={null}
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"])
```

```typescript theme={null}
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);
}
```

```bash theme={null}
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

```python theme={null}
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"])
```

```typescript theme={null}
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);
```

```bash theme={null}
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

<Columns cols={2}>
  <Card title="Voices" icon="sliders-horizontal" href="/concepts/voices">
    Understand designed voices, saved voices, voice IDs, and persisted voice settings.
  </Card>

  <Card title="Text to speech" icon="mic" href="/guides/text-to-speech">
    Use the saved `voice_id` to generate sync, async, or streaming speech.
  </Card>

  <Card title="Voice clone" icon="copy" href="/guides/voice-clone">
    Create a voice from source audio when a text prompt is not enough.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/concepts/pricing">
    Estimate preview cost, generation concurrency, and shared Studio/API credits.
  </Card>
</Columns>