> ## 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.

# Text to speech

> Convert text to audio with one-shot, streaming, and async requests.

Use text to speech for short previews, dialogue lines, and production audio generation.

## Single request

```python theme={null}
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_8rsb3nhb7645",
    text="I can't believe you brought him here!",
    output_format="mp3",
)

save(audio, Path("surprise.mp3"))
```

```typescript theme={null}
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_8rsb3nhb7645",
  { text: "I can't believe you brought him here!" },
  { outputFormat: "mp3" },
);

await save(audio, "surprise.mp3");
```

```bash theme={null}
curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_8rsb3nhb7645?output_format=mp3" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "text": "I can'\''t believe you brought him here!" }' \
  --output surprise.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

Combine `instructions` with `voice_settings` to control delivery per call. `guidance_scale` adjusts how strongly generation follows those instructions and the reference voice. The accepted range is `1.0` to `10.0`.

```json theme={null}
{
  "text": "I can't believe you brought him here!",
  "instructions": "Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.",
  "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 theme={null}
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_8rsb3nhb7645",
    text="I can't believe you brought him here!",
    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 theme={null}
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_8rsb3nhb7645",
  { text: "I can't believe you brought him here!" },
  { 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");
}
```

```bash theme={null}
curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_8rsb3nhb7645?delivery=async&output_format=mp3" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "text": "I can'\''t believe you brought him here!" }'
```

## Inspecting the result

The [logs page](https://breezeblue.ai/app/developer/logs) shows inline playback, a download link, and **Copy as cURL**.

## Continue building

<Columns cols={2}>
  <Card title="Streaming" icon="radio" href="/concepts/streaming">
    Use the streaming endpoint when playback should begin before the full response is ready.
  </Card>

  <Card title="Output formats" icon="file-audio" href="/concepts/output-format">
    Pick an encoding for browser playback, post-processing, or low-latency audio pipelines.
  </Card>

  <Card title="Managing history" icon="history" href="/guides/managing-history">
    List previous generations, download audio, and delete test runs.
  </Card>

  <Card title="API reference" icon="braces" href="/api-reference/text-to-speech/convert-text-to-speech">
    Inspect request fields, SDK examples, response bodies, and generated errors.
  </Card>
</Columns>