> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Cloning

> Klone eine Stimme aus einem kurzen Referenz-Audio-Sample mit Chatterbox HD und generiere anschließend Sprache über die Venice Audio API.

Mit Voice Cloning kannst du Sprache in einer Stimme erzeugen, die durch ein kurzes Referenz-Audio-Sample vorgegeben wird. Mit `tts-chatterbox-hd` lädst du ein Sample an `/audio/voices` hoch, speicherst das zurückgegebene `vv_...`-Voice-Handle und übergibst dieses Handle dann an `/audio/speech`.

<Note>
  Voice-Handles sind modellspezifisch. Ein mit `tts-chatterbox-hd` erstelltes Handle muss mit `tts-chatterbox-hd` verwendet werden.
</Note>

## Wie es funktioniert

1. **Upload** – Sende eine saubere Referenz-Audiodatei an `POST /audio/voices`
2. **Save** – Speichere das zurückgegebene `id`-Voice-Handle
3. **Generate** – Sende das Handle als `voice` an `POST /audio/speech`

## Voraussetzungen

* Ein Venice-API-Schlüssel
* Ein sauberes Referenz-Sample im Format MP3, WAV, FLAC oder M4A
* Mindestens 5 bis 10 Sekunden klar verständliche Sprache von einer einzigen Person

Setze deinen API-Schlüssel:

```bash theme={"system"}
export VENICE_API_KEY="your-api-key"
```

## Schritt 1: Ein Stimmensample hochladen

Erstelle ein Voice-Handle, indem du die Referenz-Audiodatei als Multipart-Form-Data hochlädst:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/voices \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=tts-chatterbox-hd" \
  -F "file=@./reference-voice.wav"
```

**Antwort (200):**

```json theme={"system"}
{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}
```

Speichere die `id` für die Sprachgenerierung:

```bash theme={"system"}
export VENICE_VOICE_ID="vv_voice_abc123xyz"
```

## Schritt 2: Sprache generieren

Übergib das geklonte Voice-Handle als `voice` im Speech-Request:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VENICE_VOICE_ID"'",
    "input": "Hello from Venice. This audio is generated with a cloned Chatterbox HD voice.",
    "response_format": "mp3"
  }' \
  --output chatterbox-clone.mp3
```

Der Response-Body ist Binär-Audio im angeforderten Format.

***

## Vollständiges Beispiel

Dieses Beispiel lädt ein Referenz-Sample hoch, extrahiert das Voice-Handle mit `jq` und schreibt das generierte Audio in `chatterbox-clone.mp3`:

```bash theme={"system"}
VOICE_ID=$(
  curl -s https://api.venice.ai/api/v1/audio/voices \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -F "model=tts-chatterbox-hd" \
    -F "file=@./reference-voice.wav" | jq -r '.id'
)

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VOICE_ID"'",
    "input": "This is a complete Chatterbox HD voice cloning example.",
    "response_format": "mp3",
    "speed": 1
  }' \
  --output chatterbox-clone.mp3
```

## Tipps für Stimmensamples

Verwende ein Sample mit einer einzigen Sprecherin oder einem einzigen Sprecher, minimalen Hintergrundgeräuschen und ohne Musik. Natürliche Sprache funktioniert besser als geflüsterte, gesungene oder stark bearbeitete Audioaufnahmen.

Längere Samples können helfen, wenn die Stimme ein markantes Sprechtempo, einen Akzent oder einen besonderen Tonfall hat – halte das Sample aber auf die Zielperson fokussiert.

## Ablauf von Handles

Chatterbox-HD-Cloning ist Zero-Shot: Venice speichert das hochgeladene Referenz-Audio nur temporär, und das Modell liest es ein, wenn du Sprache synthetisierst. Es wird kein dauerhaftes Voice-Template erstellt.

Voice-Handles laufen automatisch nach 7 Tagen ab. Nach Ablauf eines Handles lädst du das Referenz-Sample erneut hoch, um ein neues `vv_...`-Handle zu erzeugen.

## Cloning-Support erkennen

Modelle, die Cloning unterstützen, enthalten ein `voice_cloning`-Objekt in der Model-Spec. Frage die TTS-Modelle ab, um unterstützte Formate, Mindest-Sample-Länge und Aufbewahrung zu prüfen:

```bash theme={"system"}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

`tts-chatterbox-hd` weist Folgendes aus:

```json theme={"system"}
{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "m4a"],
    "min_sample_seconds": 5,
    "retention_days": 7
  }
}
```

***

## API-Parameter

### Voice erstellen

| Feld    | Typ    | Pflicht | Beschreibung                                                             |
| ------- | ------ | ------- | ------------------------------------------------------------------------ |
| `model` | string | Ja      | Muss `tts-chatterbox-hd` sein                                            |
| `file`  | file   | Ja      | Referenz-Audio-Sample. Unterstützte Formate sind MP3, WAV, FLAC und M4A. |

### Sprache generieren

| Feld              | Typ     | Pflicht | Default | Beschreibung                                                                            |
| ----------------- | ------- | ------- | ------- | --------------------------------------------------------------------------------------- |
| `model`           | string  | Ja      | -       | Muss mit dem Modell übereinstimmen, das zum Erstellen des Voice-Handles verwendet wurde |
| `voice`           | string  | Ja      | -       | Das von `POST /audio/voices` zurückgegebene `vv_...`-Handle                             |
| `input`           | string  | Ja      | -       | Zu synthetisierender Text, bis zu 4096 Zeichen                                          |
| `response_format` | string  | Nein    | `mp3`   | `mp3`, `opus`, `aac`, `flac`, `wav` oder `pcm`                                          |
| `speed`           | number  | Nein    | `1`     | Sprechgeschwindigkeit von `0.25` bis `4.0`                                              |
| `temperature`     | number  | Nein    | -       | Sampling-Temperatur von `0` bis `2`. Höhere Werte können zu mehr Variation führen.      |
| `streaming`       | boolean | Nein    | `false` | Audio Satz für Satz streamen                                                            |

## Häufige Fehler

| Status | Ursache                                                             | Lösung                                                                                                   |
| ------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `400`  | Nicht unterstützter Audio-Container oder inkompatibles Voice-Handle | Nutze MP3, WAV, FLAC oder M4A und kombiniere das Handle mit demselben Modell, mit dem es erstellt wurde. |
| `401`  | Fehlender oder ungültiger API-Schlüssel                             | Sende `Authorization: Bearer $VENICE_API_KEY`.                                                           |
| `402`  | Unzureichendes Guthaben                                             | Lade dein Venice-Guthaben auf.                                                                           |
| `413`  | Hochgeladene Datei ist zu groß                                      | Verwende ein kürzeres oder stärker komprimiertes Referenz-Sample.                                        |
| `429`  | Rate Limit überschritten                                            | Versuche es erneut, nachdem das Rate-Limit-Fenster zurückgesetzt wurde.                                  |