Voice Remix

Voice Remix changes how an existing voice sounds while keeping its language. Use your own voice or an available official voice; favoriting another creator’s voice does not grant Remix access. Saving a candidate creates a separate private voice and leaves the source unchanged. For a different language, use Voice Localize.

Generate a candidate

Provide a voice_id and either a prompt or preset_id. Each request creates one candidate. Custom descriptions are automatically enhanced into a performance instruction and a matching audition script in the source voice’s language.

cURL
Python
TypeScript
CLI

curl https://api.breeze.blue/v1/voice-previews/remix \
  -H "xi-api-key: $BREEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: narrator-older-01" \
  -d '{"voice_id":"voc_example","prompt":"Make the voice older and softer."}'

from breeze_blue import BreezeBlue

client = BreezeBlue()  # Reads BREEZE_API_KEY.
job = client.voices.create_remix_preview(
    voice_id="voc_example",
    prompt="Make the voice older and softer.",
    idempotency_key="narrator-older-01",
)
print(job["generation_job_id"])

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

const client = new BreezeBlueClient({ apiKey: process.env.BREEZE_API_KEY! });
const job = await client.voices.createRemixPreview(
  { voiceId: "voc_example", prompt: "Make the voice older and softer." },
  { headers: { "Idempotency-Key": "narrator-older-01" } },
);
console.log(job.generationJobId);

breeze voice remix --voice voc_example \
  --prompt "Make the voice older and softer." \
  --idempotency-key narrator-older-01 --agent

The CLI waits for the candidate and returns JSON. In an interactive terminal, omit --agent to audition it automatically, or use --no-play to skip playback.

Replace voc_example with your source voice ID. An API submission returns 202 with generation_job_id and status. Each successful candidate costs 100 credits. Failed generation releases its reservation; browsing presets, preparing input, auditioning, and saving do not add a generation charge.

Use a preset

GET /v1/voice-previews/remix/presets lists presets for age, gender, pitch, pacing, energy, emotion, role-play, and delivery. Each includes an ID, instruction, script, suggested strength, and sample audio URL. The sample demonstrates the style; it is not a remix of your chosen voice. Use voices.list_remix_presets() in Python, voices.listRemixPresets() in TypeScript, or:

breeze voice remix presets --agent
breeze voice remix --voice voc_example --preset AGE_05_01 --agent

A preset uses its curated instruction and script without Enhance. If the source speaks another language, both are translated faithfully. Supplying an edited prompt makes it custom input and runs Enhance, even if preset_id is present.

Compare strengths

guidance_scale accepts 1–10 and defaults to 4. The CLI flag is --guidance.

Strength	Value
Stable	2
Expressive	4
Creative	6
Intense	8

To compare candidates with the same instruction and script, call POST /v1/voice-previews/remix/prepare with the same voice_id, prompt, and preset_id you plan to generate. The response includes instruction, text, language_code, source_voice, and a preparation_token valid for 24 hours. Pass that token to each create request. It is bound to your account, source voice, language, prompt, and preset; changing them requires another preparation. Omitting the token prepares input as part of submission.

Client	Prepare	Submit with token
Python	`voices.prepare_remix_preview(...)`	`preparation_token=...`
TypeScript	`voices.prepareRemixPreview(...)`	`preparationToken: ...`
CLI	`breeze voice remix prepare ... --agent`	`--preparation-token ...`

Web’s Auto comparison corresponds to three separate candidates at 4, 6, and 8, using one preparation. Submit and poll within your account’s generation concurrency limit. Three successful candidates cost 300 credits. Keep the candidate IDs you like and regenerate only the others; selection itself does not create a saved voice or spend credits.

Audition and save

Poll GET /v1/voice-previews/remix/{generation_job_id} until status is ready. Stop polling on failed or cancelled and read error. SDK methods are voices.get_remix_preview(id) and voices.getRemixPreview(id); the CLI command is breeze voice remix status <generation_job_id> --agent. The result contains:

generated_voice_id: available when ready; use it to audition or save.
text and instruction: the candidate’s audition script and prepared direction.
guidance_scale: the strength used for this candidate.
comparison_audio_url and comparison_text: the source recording and its own transcript. It may speak different words from the candidate.
source_voice: source ID, name, and description captured for the request.

Download audio with GET /v1/voice-previews/{generated_voice_id}/stream. Save with POST /v1/voice-previews/{generated_voice_id}/save, supplying the returned language_code. SDK methods are stream_preview / save_preview (streamPreview / savePreview in TypeScript).

breeze voice preview play gvi_example
breeze voice preview save gvi_example --language en --agent

Replace gvi_example and en with the returned preview ID and language. Name and description default to the source voice’s values; override them with voice_name / voice_description in the API or --name / --description in the CLI. Save only ready candidates. Use the saved voice_id for Text to Speech.

Retry without duplicating a candidate

Retain the job ID as soon as submission succeeds. A polling timeout does not cancel generation; query the same job again. If submission timed out before you received an ID, retry with the same Idempotency-Key and input. Changed input with that key returns CONFLICT; a concurrent submission can also return CONFLICT until the first request finishes. Use a new key for each intentionally new candidate. The source needs usable audio, a matching transcript, and a comparison sample of 2–500 characters. Source validation and input preparation happen before generation credits are reserved. A failed or expired preparation must be corrected before submitting again.

Get started

Concepts

Guides

Reference

Generate a candidate

Use a preset

Compare strengths

Audition and save

Retry without duplicating a candidate

​Generate a candidate

​Use a preset

​Compare strengths

​Audition and save

​Retry without duplicating a candidate

Generate a candidate

Use a preset

Compare strengths

Audition and save

Retry without duplicating a candidate