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

# Clonazione vocale

> Clona una voce da un breve campione audio di riferimento con Chatterbox HD, salva l'handle vocale restituito e genera parlato tramite la Venice Audio API.

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

<Note>
  Gli handle vocali sono specifici per modello. Un handle creato con `tts-chatterbox-hd` deve essere utilizzato con `tts-chatterbox-hd`.
</Note>

## Come funziona

1. **Carica** - Invia un file audio di riferimento pulito a `POST /audio/voices`
2. **Salva** - Memorizza 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 M4A
* Almeno 5-10 secondi di parlato chiaro da un singolo speaker

Imposta la tua chiave API:

```bash theme={null}
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:

```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"
```

**Risposta (200):**

```json theme={null}
{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}
```

Salva l'`id` per la generazione del parlato:

```bash theme={null}
export VENICE_VOICE_ID="vv_voice_abc123xyz"
```

## Passaggio 2: genera il parlato

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

```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.",
    "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`:

```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.",
    "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:

```bash theme={null}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

`tts-chatterbox-hd` pubblicizza:

```json theme={null}
{
  "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.                                   |