Voice-Cloning-Guide | Venice API Docs

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.

Voice-Handles sind modellspezifisch. Ein mit tts-chatterbox-hd erstelltes Handle muss mit tts-chatterbox-hd verwendet werden.

Wie es funktioniert

Upload – Sende eine saubere Referenz-Audiodatei an POST /audio/voices
Speichern – Speichere das zurückgegebene id-Voice-Handle
Generieren – 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 MP4
Mindestens 5 bis 10 Sekunden klar verständliche Sprache von einer einzigen Person

Setze deinen API-Schlüssel:

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:

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"

Wenn du curl -F verwendest, setze den Content-Type nicht manuell. curl fügt den multipart/form-data-Header und den erforderlichen Boundary-Wert automatisch hinzu. Antwort (200):

{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}

Speichere die id für die Sprachgenerierung:

export VENICE_VOICE_ID="vv_voice_abc123xyz"

Schritt 2: Sprache generieren

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

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."
  }' \
  --output chatterbox-clone.wav

Der Response-Body ist Binär-Audio im Standardformat des Modells und kein JSON. tts-chatterbox-hd verwendet derzeit standardmäßig WAV.

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.wav:

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.",
    "speed": 1
  }' \
  --output chatterbox-clone.wav

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:

curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"

tts-chatterbox-hd weist Folgendes aus:

{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "mp4"],
    "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 MP4.

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	Modellspezifisch	Optionales Überschreiben des Ausgabeformats. Prüfe vor dem Setzen die unterstützten und standardmäßigen Formate des Modells.
`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

Die erfolgreiche Speech-Antwort ist Binär-Audio, und ihr Content-Type gibt das zurückgegebene Format an. Du kannst response_format weglassen, um das Modell-Standardformat zu verwenden. Frage model_spec.supported_formats und model_spec.default_format über GET /models?type=tts ab, bevor du das Format überschreibst; die Anforderung eines nicht unterstützten Formats gibt HTTP 400 zurück.

Häufige Fehler

Status	Ursache	Lösung
`400`	Nicht unterstützter Audio-Container oder inkompatibles Voice-Handle	Nutze MP3, WAV, FLAC oder MP4 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.

Dokumentation

Erste Schritte

Text & Chat

Bild, Video & Audio

Suche & RAG

Agenten & Integrationen

Coding-Tools

Agenten-Tools

SDKs & Frameworks

Voice Cloning

Wie es funktioniert

Voraussetzungen

Schritt 1: Ein Stimmensample hochladen

Schritt 2: Sprache generieren

Vollständiges Beispiel

Tipps für Stimmensamples

Ablauf von Handles

Cloning-Support erkennen

API-Parameter

Voice erstellen

Sprache generieren

Häufige Fehler

​Wie es funktioniert

​Voraussetzungen

​Schritt 1: Ein Stimmensample hochladen

​Schritt 2: Sprache generieren

​Vollständiges Beispiel

​Tipps für Stimmensamples

​Ablauf von Handles

​Cloning-Support erkennen

​API-Parameter

​Voice erstellen

​Sprache generieren

​Häufige Fehler

Wie es funktioniert

Voraussetzungen

Schritt 1: Ein Stimmensample hochladen

Schritt 2: Sprache generieren

Vollständiges Beispiel

Tipps für Stimmensamples

Ablauf von Handles

Cloning-Support erkennen

API-Parameter

Voice erstellen

Sprache generieren

Häufige Fehler