Guida alla clonazione vocale

La clonazione vocale ti consente di generare parlato con una voce fornita da un breve campione audio di riferimento. Con tts-chatterbox-hd, carica un campione su /audio/voices, salva l’handle vocale vv_... restituito e poi passa quell’handle a /audio/speech.

Gli handle vocali sono specifici per modello. Un handle creato con tts-chatterbox-hd deve essere utilizzato con tts-chatterbox-hd.

Come funziona

Carica - Invia un file audio di riferimento pulito a POST /audio/voices
Salva - Memorizza l’handle vocale id restituito
Genera - Invia l’handle come voice in POST /audio/speech

Prerequisiti

Una chiave API Venice
Un campione di riferimento pulito in formato MP3, WAV, FLAC o M4A
Almeno 5-10 secondi di parlato chiaro da un singolo speaker

Imposta la tua chiave API:

export VENICE_API_KEY="your-api-key"

Passaggio 1: carica un campione vocale

Crea un handle vocale caricando l’audio di riferimento come dati form multipart:

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"

Risposta (200):

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

Salva l’id per la generazione del parlato:

export VENICE_VOICE_ID="vv_voice_abc123xyz"

Passaggio 2: genera il parlato

Passa l’handle della voce clonata come voice nella richiesta di parlato:

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

Il corpo della risposta è audio binario nel formato richiesto.

Esempio completo

Questo esempio carica un campione di riferimento, estrae l’handle vocale con jq e scrive l’audio generato in chatterbox-clone.mp3:

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

Suggerimenti per il campione vocale

Utilizza un campione con un solo speaker, rumore di fondo minimo e senza musica. Il parlato naturale funziona meglio dell’audio sussurrato, cantato o pesantemente elaborato. I campioni più lunghi possono essere utili quando la voce ha un ritmo, un accento o un tono distintivi, ma mantieni il campione focalizzato sullo speaker target.

Scadenza dell’handle

La clonazione Chatterbox HD è zero-shot: Venice memorizza temporaneamente l’audio di riferimento caricato e il modello lo legge quando sintetizzi il parlato. Non viene creato alcun template vocale persistente. Gli handle vocali scadono automaticamente dopo 7 giorni. Dopo la scadenza di un handle, carica nuovamente il campione di riferimento per creare un nuovo handle vv_....

Scopri il supporto alla clonazione

I modelli che supportano la clonazione includono un oggetto voice_cloning nelle specifiche del modello. Interroga i modelli TTS per verificare i formati supportati, la lunghezza minima del campione e la conservazione:

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

tts-chatterbox-hd pubblicizza:

{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "m4a"],
    "min_sample_seconds": 5,
    "retention_days": 7
  }
}

Parametri API

Crea voce

Campo	Tipo	Obbligatorio	Descrizione
`model`	string	Sì	Deve essere `tts-chatterbox-hd`
`file`	file	Sì	Campione audio di riferimento. I formati supportati sono MP3, WAV, FLAC e M4A.

Genera parlato

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
`model`	string	Sì	-	Deve corrispondere al modello utilizzato per creare l’handle vocale
`voice`	string	Sì	-	L’handle `vv_...` restituito da `POST /audio/voices`
`input`	string	Sì	-	Testo da sintetizzare, fino a 4096 caratteri
`response_format`	string	No	`mp3`	`mp3`, `opus`, `aac`, `flac`, `wav` o `pcm`
`speed`	number	No	`1`	Velocità del parlato da `0.25` a `4.0`
`temperature`	number	No	-	Temperatura di campionamento da `0` a `2`. Valori più alti possono aggiungere variazione.
`streaming`	boolean	No	`false`	Trasmetti l’audio frase per frase

Errori comuni

Stato	Causa	Soluzione
`400`	Container audio non supportato o handle vocale incompatibile	Usa MP3, WAV, FLAC o M4A e abbina l’handle allo stesso modello utilizzato per crearlo.
`401`	Chiave API mancante o non valida	Invia `Authorization: Bearer $VENICE_API_KEY`.
`402`	Saldo insufficiente	Ricarica il tuo saldo Venice.
`413`	Il file caricato è troppo grande	Usa un campione di riferimento più breve o più compresso.
`429`	Limite di velocità superato	Riprova dopo il reset della finestra del rate limit.

Documentazione

Per iniziare

Testo e chat

Immagini, video e audio

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Clonazione vocale

Come funziona

Prerequisiti

Passaggio 1: carica un campione vocale

Passaggio 2: genera il parlato

Esempio completo

Suggerimenti per il campione vocale

Scadenza dell’handle

Scopri il supporto alla clonazione

Parametri API

Crea voce

Genera parlato

Errori comuni

​Come funziona

​Prerequisiti

​Passaggio 1: carica un campione vocale

​Passaggio 2: genera il parlato

​Esempio completo

​Suggerimenti per il campione vocale

​Scadenza dell’handle

​Scopri il supporto alla clonazione

​Parametri API

​Crea voce

​Genera parlato

​Errori comuni

Come funziona

Prerequisiti

Passaggio 1: carica un campione vocale

Passaggio 2: genera il parlato

Esempio completo

Suggerimenti per il campione vocale

Scadenza dell’handle

Scopri il supporto alla clonazione

Parametri API

Crea voce

Genera parlato

Errori comuni