Cloning a voice

Clone a voice from an audio sample.

Voice cloning is a two-step flow: upload one sample to generate a preview, then save the preview as a reusable voice. Adjust text and instructions on the preview. Speaker consent is required; see voice consent.

Sample requirements

• Upload exactly one sample file.
• Use a single speaker with no background music or noise.
• Use MP3 or WAV.
• Minimum duration: 3 seconds. There is no maximum.
• Maximum file size: 5 MB.

Step 1: Create a preview

Breeze analyzes the first 60 seconds of the upload: it transcribes that stretch, detects its language, and keeps at most 30 seconds of it, ending on the last complete sentence that fits. Without usable punctuation the cut falls back to a natural pause, and failing that to the last whole word — it never lands mid-word. The excerpt starts just before the first word, keeping up to a second of leading silence, and is normalized to -18 LUFS so a quiet or hot recording does not bias the clone.

The stored reference is that trimmed, normalized excerpt together with its transcript, not the original file. A long recording therefore clones as well as a tightly edited one: upload the whole take and let Breeze pick the cut. Put the audio you want cloned in the first minute.

import os
from pathlib import Path

from breeze_blue import BreezeBlue

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

preview = client.voices.create_clone_preview(
    name="My narrator",
    file=Path("narrator.wav"),
    language_code="en",
    text="Welcome to the preview.",
    instructions="Stay close to the reference tone.",
)

print(preview["generated_voice_id"])

import { readFile } from "node:fs/promises";
import { BreezeBlueClient } from "@breeze.blue/sdk";

const client = new BreezeBlueClient({
  apiKey: process.env.BREEZE_API_KEY!,
});

const preview = await client.voices.createClonePreview({
  name: "My narrator",
  file: {
    data: await readFile("narrator.wav"),
    filename: "narrator.wav",
    contentType: "audio/wav",
  },
  languageCode: "en",
  text: "Welcome to the preview.",
  instructions: "Stay close to the reference tone.",
});

console.log(preview.generatedVoiceId);

curl -X POST "https://api.breeze.blue/v1/voice-previews/clone" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -F "name=My narrator" \
  -F "language_code=en" \
  -F "files=@./narrator.wav" \
  -F "text=Welcome to the preview." \
  -F "instructions=Stay close to the reference tone."

The response contains a generated_voice_id, not a saved voice_id. Pass language_code when the sample language is known; Breeze may detect it from the analyzed excerpt when omitted. text defaults to the Breeze clone script in the confirmed reference language when omitted or empty. instructions defaults to none. SDKs also accept files with exactly one item.

Step 2: Stream the preview

import os
from pathlib import Path

from breeze_blue import BreezeBlue, save

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

preview_audio = client.voices.stream_preview(
    generated_voice_id="gvi_01hpreview",
)
save(preview_audio, Path("clone-preview.mp3"))

import { BreezeBlueClient } from "@breeze.blue/sdk";
import { save } from "@breeze.blue/sdk/node";

const client = new BreezeBlueClient({
  apiKey: process.env.BREEZE_API_KEY!,
});

const previewAudio = await client.voices.streamPreview("gvi_01hpreview");
await save(previewAudio, "clone-preview.mp3");

curl "https://api.breeze.blue/v1/voice-previews/$GENERATED_VOICE_ID/stream" \
  -H "xi-api-key: $BREEZE_API_KEY" \
  --output clone-preview.mp3

Step 3: Save the preview as a 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="My narrator",
    language_code="en",
)

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: "My narrator",
  languageCode: "en",
});

console.log(voice.voiceId);

Pass the reference transcript’s language when saving. language_code is required so later cross-language synthesis can distinguish the voice’s reference language from the requested speech language.

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": "My narrator",
    "language_code": "en"
  }'

Saving consumes a voice slot. Subsequent POST /v1/text-to-speech/{voice_id} calls use the stored reference sample and its transcript, not the preview audio.

Editing or deleting a saved voice

• Update tags and the description with PATCH /v1/voices/{voice_id}.
• Tune defaults with PATCH /v1/voices/{voice_id}/settings.
• Remove the voice with DELETE /v1/voices/{voice_id}.

Continue building

Create clone preview

Upload one audio sample and inspect the name, text, and instructions request fields.

Stream voice preview

Listen to a generated_voice_id preview before deciding to save it.

Save voice preview

Persist the preview as a reusable voice; saving consumes a voice slot.

CLI voice clone

Clone from an audio sample in the terminal with breeze voice clone.

Voices

Learn how cloned voices, designed voices, public voices, and voice settings fit together.

Text to speech

Use the saved cloned voice for dialogue lines, previews, or production audio.