Guida al Voice Cloning | Documentazione API Venice

Il voice cloning ti permette di generare audio in 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 usato con tts-chatterbox-hd.

Come funziona

Carica - Invia un file audio di riferimento pulito a POST /audio/voices
Salva - Conserva 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 MP4
Almeno 5-10 secondi di parlato chiaro da un singolo parlante

Imposta la tua chiave API:

export VENICE_API_KEY="your-api-key"

Passo 1: Carica un campione vocale

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

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"

Quando usi curl -F, non impostare manualmente Content-Type. curl aggiunge automaticamente l’header multipart/form-data e il boundary richiesto. Risposta (200):

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

Salva l’id per la generazione dell’audio:

export VENICE_VOICE_ID="vv_voice_abc123xyz"

Passo 2: Genera l’audio

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

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

Il corpo della risposta è audio binario nel formato predefinito del modello, non JSON. Attualmente tts-chatterbox-hd usa WAV come formato predefinito.

Esempio completo

Questo esempio carica un campione di riferimento, estrae l’handle vocale con jq e scrive l’audio generato 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

Consigli per il campione vocale

Usa un campione con un solo parlante, rumore di fondo minimo e senza musica. Il parlato naturale funziona meglio dell’audio sussurrato, cantato o elaborato pesantemente. Campioni più lunghi possono aiutare quando la voce ha ritmo, accento o tono distintivi, ma mantieni il campione focalizzato sul parlante di riferimento.

Scadenza dell’handle

Il cloning di Chatterbox HD è zero-shot: Venice conserva temporaneamente l’audio di riferimento caricato e il modello lo legge quando sintetizzi l’audio. Non viene creato alcun modello vocale persistente. Gli handle vocali scadono automaticamente dopo 7 giorni. Quando un handle scade, carica di nuovo il campione di riferimento per creare un nuovo handle vv_....

Scoprire il supporto al cloning

I modelli che supportano il cloning includono un oggetto voice_cloning nella specifica del modello. Interroga i modelli TTS per verificare i formati supportati, la lunghezza minima del campione e la ritenzione:

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

tts-chatterbox-hd espone:

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

Parametri API

Creazione 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 MP4.

Generazione audio

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
`model`	string	Sì	-	Deve corrispondere al modello usato 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	Specifico per modello	Override opzionale del formato di output. Verifica i formati supportati e quello predefinito del modello prima di impostarlo.
`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`	Trasmette l’audio frase per frase

La risposta di sintesi di successo è audio binario e il suo Content-Type identifica il formato restituito. Puoi omettere response_format per usare il formato predefinito del modello. Interroga model_spec.supported_formats e model_spec.default_format tramite GET /models?type=tts prima di sovrascriverlo; richiedere un formato non supportato restituisce HTTP 400.

Errori comuni

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

Documentazione

Per iniziare

Testo e chat

Immagini, video e audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Voice Cloning

Come funziona

Prerequisiti

Passo 1: Carica un campione vocale

Passo 2: Genera l’audio

Esempio completo

Consigli per il campione vocale

Scadenza dell’handle

Scoprire il supporto al cloning

Parametri API

Creazione voce

Generazione audio

Errori comuni

​Come funziona

​Prerequisiti

​Passo 1: Carica un campione vocale

​Passo 2: Genera l’audio

​Esempio completo

​Consigli per il campione vocale

​Scadenza dell’handle

​Scoprire il supporto al cloning

​Parametri API

​Creazione voce

​Generazione audio

​Errori comuni

Come funziona

Prerequisiti

Passo 1: Carica un campione vocale

Passo 2: Genera l’audio

Esempio completo

Consigli per il campione vocale

Scadenza dell’handle

Scoprire il supporto al cloning

Parametri API

Creazione voce

Generazione audio

Errori comuni