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

# Voice Remix

> Change an existing voice with a description or preset, compare previews, and save the result.

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](/guides/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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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."}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

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:

```bash theme={null}
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).

```bash theme={null}
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](/guides/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.