> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-mintlify-86b9f77a.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Voice Cloning > Clona una voce a partire da un breve campione audio di riferimento usando Chatterbox HD, salva l'handle vocale restituito e genera audio tramite la Venice Audio API. 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 1. **Carica** - Invia un file audio di riferimento pulito a `POST /audio/voices` 2. **Salva** - Conserva l'handle vocale `id` restituito 3. **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: ```bash theme={null} 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: ```bash theme={null} 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):** ```json theme={null} { "id": "vv_voice_abc123xyz", "model": "tts-chatterbox-hd" } ``` Salva l'`id` per la generazione dell'audio: ```bash theme={null} export VENICE_VOICE_ID="vv_voice_abc123xyz" ``` ## Passo 2: Genera l'audio Passa l'handle della voce clonata come `voice` nella richiesta di sintesi: ```bash theme={null} 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`: ```bash theme={null} 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: ```bash theme={null} curl "https://api.venice.ai/api/v1/models?type=tts" \ -H "Authorization: Bearer $VENICE_API_KEY" ``` `tts-chatterbox-hd` espone: ```json theme={null} { "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. |