BreezeDocs
Get API key
POSThttps://api.breeze.blue/v1/text-to-speech/{voice_id}

Convert text to speech

Synthesize text to audio using the given voice.

Authentication

API key: Send your Breeze Developer API key with the xi-api-key header.

Headers

FieldTypeDescription
xi-api-keyrequiredstringYour Breeze Developer API key. See authentication.
content-typerequiredstringapplication/json

Path parameters

FieldTypeDescription
voice_idrequiredstringVoice identifier to synthesize. Use GET /v1/voices to discover available IDs.

Query parameters

FieldTypeDescription
output_formatstring
default: mp3
Audio output encoding. Supported values: mp3, wav, flac, pcm, aac, opus. Default: mp3.
deliverystring
default: sync
Use sync for the default audio response, or async to create a background generation job and poll for the result. Async delivery does not bypass concurrent generation limits.

Request body

FieldTypeDescription
textrequiredstringText to synthesize.
model_idstringmodel_id request field for TtsRequest.
language_codestringlanguage_code request field for TtsRequest.
instructionsstringinstructions request field for TtsRequest.
voice_settingsobjectvoice_settings request field for TtsRequest.
voice_settings.guidance_scalenumbervoice_settings.guidance_scale request field for VoiceSettingsPayload.

Example request

python from pathlib import Path from breeze_blue import save import os from breeze_blue import BreezeBlue client = BreezeBlue(api_key=os.environ["BREEZE_API_KEY"]) audio = client.text_to_speech.convert( voice_id="voc_xeh3w54cqvnp", text="Hello from Breeze Blue.", model_id="bluebell-v1-en", voice_settings={"guidance_scale": 1.2}, ) save(audio, Path("out.mp3")) typescript import { save } from "@breeze.blue/sdk/node"; import { BreezeBlueClient } from "@breeze.blue/sdk"; const client = new BreezeBlueClient({ apiKey: process.env.BREEZE_API_KEY!, }); const audio = await client.textToSpeech.convert( "voc_xeh3w54cqvnp", { text: "Hello from Breeze Blue.", modelId: "bluebell-v1-en", voiceSettings: { guidanceScale: 1.2 }, }, ); await save(audio, "out.mp3"); curl curl -X POST "https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp" \ -H "xi-api-key: $BREEZE_API_KEY" \ -H "content-type: application/json" \ --data '{ "model_id": "bluebell-v1-en", "text": "Hello from Breeze Blue.", "voice_settings": { "guidance_scale": 1.2 } }'
from pathlib import Path

from breeze_blue import save

import os

from breeze_blue import BreezeBlue

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

audio = client.text_to_speech.convert(
    voice_id="voc_xeh3w54cqvnp",
    text="Hello from Breeze Blue.",
    model_id="bluebell-v1-en",
    voice_settings={"guidance_scale": 1.2},
)
save(audio, Path("out.mp3"))

Response

Binary audio stream. Content-Type matches the requested output_format.

Content types: audio/mpeg, audio/wav, audio/flac, audio/aac, audio/opus, audio/pcm

Response headers:

  • history-item-id: History item ID for the generated audio.
  • x-breeze-api-key-id: Public API key identifier used to authenticate the request, when an API key was used.
Binary audio/mpeg, audio/wav, audio/flac, audio/aac, audio/opus, audio/pcm response body

Errors

  • VALIDATION_ERROR — The request body failed schema validation.
  • BAD_REQUEST — The request body or query parameter is not valid for this endpoint.
  • RESOURCE_NOT_FOUND — The voice_id does not exist or is not accessible.
  • GENERATION_CONCURRENCY_EXCEEDED — Your plan's concurrent generation limit was reached. Please retry shortly.
  • GENERATION_CAPACITY_EXCEEDED — Generation capacity is temporarily exhausted.
  • UPSTREAM_GENERATION_ERROR — The downstream generation service failed.
  • UPSTREAM_TIMEOUT — The downstream generation service timed out.

See the full list on errors.

Notes

  • Use voice_settings.guidance_scale to adjust how strongly generation follows the prompt and reference voice.