> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/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, quindi genera il 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={"system"}
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={"system"}
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={"system"}
{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}
```

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

```bash theme={"system"}
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={"system"}
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={"system"}
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={"system"}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

`tts-chatterbox-hd` pubblicizza:

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