BreezeDocs
Get API key
POSThttps://api.breeze.blue/v1/voice-previews/design

Create design previews

Generate temporary voice previews from a text description.

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

Query parameters

FieldTypeDescription
output_formatstring
default: mp3
Audio format for the embedded preview payloads. Supported values: mp3, wav, flac, pcm, aac, opus. Default: mp3.

Request body

FieldTypeDescription
voice_descriptionrequiredstringText description of the desired voice.
textstringtext request field for VoiceDesignRequest.
model_idstringmodel_id request field for VoiceDesignRequest.
language_codestringlanguage_code request field for VoiceDesignRequest.
guidance_scalenumberguidance_scale request field for VoiceDesignRequest.
preview_countintegerpreview_count request field for VoiceDesignRequest.

Example request

python import os from breeze_blue import BreezeBlue client = BreezeBlue(api_key=os.environ["BREEZE_API_KEY"]) design = client.voices.create_design_preview( voice_description="Warm, intimate narrator with crisp diction.", text="Welcome to Breeze Blue.", language_code="en", preview_count=3, ) for preview in design["previews"]: print(preview["generated_voice_id"]) typescript import { BreezeBlueClient } from "@breeze.blue/sdk"; const client = new BreezeBlueClient({ apiKey: process.env.BREEZE_API_KEY!, }); const design = await client.voices.createDesignPreview({ voiceDescription: "Warm, intimate narrator with crisp diction.", text: "Welcome to Breeze Blue.", languageCode: "en", previewCount: 3, }); for (const preview of design.previews) { console.log(preview.generatedVoiceId); } curl curl -X POST "https://api.breeze.blue/v1/voice-previews/design" \ -H "xi-api-key: $BREEZE_API_KEY" \ -H "content-type: application/json" \ --data '{ "language_code": "en", "preview_count": 3, "text": "Welcome to Breeze Blue.", "voice_description": "Warm, intimate narrator with crisp diction." }'
import os

from breeze_blue import BreezeBlue

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

design = client.voices.create_design_preview(
    voice_description="Warm, intimate narrator with crisp diction.",
    text="Welcome to Breeze Blue.",
    language_code="en",
    preview_count=3,
)

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

Response

Generated voice previews.

Content types: application/json

Response headers:

  • x-breeze-api-key-id: Public API key identifier used to authenticate the request, when an API key was used.
{
  "previews": [
    {
      "generated_voice_id": "gvi_01hpreview",
      "audio_base_64": "string",
      "media_type": "audio/mpeg",
      "duration_secs": 0.5
    }
  ],
  "text": "Hello from Breeze Blue."
}

Errors

  • BAD_REQUEST — The request body or output option is not valid for this endpoint.
  • VALIDATION_ERROR — The request body failed validation.
  • GENERATION_CONCURRENCY_EXCEEDED — Your plan's concurrent generation limit was reached. Please retry shortly.
  • VOICE_DESIGN_FAILED — Voice design failed.
  • UPSTREAM_GENERATION_ERROR — The generation service failed.

See the full list on errors.

Notes

  • Supported optional controls: preview_count, guidance_scale, model_id, language_code. preview_count defaults to 3 and accepts values from 1 to 3.