> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-ce69695c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Cloning

> Clona una voce da un breve campione audio con 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`.

<Note>
  Gli handle vocali sono specifici per modello. Un handle creato con `tts-chatterbox-hd` deve essere usato con `tts-chatterbox-hd`. Il voice cloning è text-to-speech a partire da un campione di riferimento. Per registrare di nuovo una registrazione esistente in un'altra voce, usa invece l'API [Voice Changer](/it/guides/media/voice-changer).
</Note>

## 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.