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

# Clonage vocal

> Clonez une voix à partir d'un court échantillon audio de référence avec Chatterbox HD, puis générez de la parole via l'API Venice Audio.

Le clonage vocal vous permet de générer de la parole dans une voix fournie par un court échantillon audio de référence. Avec `tts-chatterbox-hd`, téléversez un échantillon vers `/audio/voices`, enregistrez le handle de voix `vv_...` retourné, puis transmettez ce handle à `/audio/speech`.

<Note>
  Les handles de voix sont spécifiques à chaque modèle. Un handle créé avec `tts-chatterbox-hd` doit être utilisé avec `tts-chatterbox-hd`.
</Note>

## Fonctionnement

1. **Téléversement** — Envoyez un fichier audio de référence propre à `POST /audio/voices`
2. **Enregistrement** — Stockez le handle de voix `id` retourné
3. **Génération** — Envoyez le handle comme `voice` dans `POST /audio/speech`

## Prérequis

* Une clé API Venice
* Un échantillon de référence propre au format MP3, WAV, FLAC ou M4A
* Au moins 5 à 10 secondes de parole claire d'un seul locuteur

Définissez votre clé API :

```bash theme={"system"}
export VENICE_API_KEY="your-api-key"
```

## Étape 1 : téléverser un échantillon vocal

Créez un handle de voix en téléversant l'audio de référence sous forme de données de formulaire 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"
```

**Réponse (200) :**

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

Enregistrez l'`id` pour la génération de parole :

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

## Étape 2 : générer la parole

Transmettez le handle de voix cloné comme `voice` dans la requête de synthèse :

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

Le corps de la réponse est de l'audio binaire au format demandé.

***

## Exemple complet

Cet exemple téléverse un échantillon de référence, extrait le handle de voix avec `jq` et écrit l'audio généré dans `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
```

## Conseils pour l'échantillon vocal

Utilisez un échantillon avec un seul locuteur, un bruit de fond minimal et sans musique. La parole naturelle fonctionne mieux que l'audio chuchoté, chanté ou fortement traité.

Des échantillons plus longs peuvent être utiles lorsque la voix a un rythme, un accent ou un ton distinctifs, mais gardez l'échantillon centré sur le locuteur cible.

## Expiration des handles

Le clonage Chatterbox HD est zero-shot : Venice stocke temporairement l'audio de référence téléversé, et le modèle le lit lorsque vous synthétisez de la parole. Aucun modèle vocal persistant n'est créé.

Les handles de voix expirent automatiquement après 7 jours. Une fois qu'un handle a expiré, téléversez à nouveau l'échantillon de référence pour créer un nouveau handle `vv_...`.

## Découvrir la prise en charge du clonage

Les modèles qui prennent en charge le clonage incluent un objet `voice_cloning` dans la spécification du modèle. Interrogez les modèles TTS pour vérifier les formats pris en charge, la durée minimale de l'échantillon et la rétention :

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

`tts-chatterbox-hd` annonce :

```json theme={"system"}
{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "m4a"],
    "min_sample_seconds": 5,
    "retention_days": 7
  }
}
```

***

## Paramètres de l'API

### Créer une voix

| Champ   | Type   | Requis | Description                                                                            |
| ------- | ------ | ------ | -------------------------------------------------------------------------------------- |
| `model` | string | Oui    | Doit être `tts-chatterbox-hd`                                                          |
| `file`  | file   | Oui    | Échantillon audio de référence. Les formats pris en charge sont MP3, WAV, FLAC et M4A. |

### Générer la parole

| Champ             | Type    | Requis | Par défaut | Description                                                                                           |
| ----------------- | ------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------- |
| `model`           | string  | Oui    | -          | Doit correspondre au modèle utilisé pour créer le handle de voix                                      |
| `voice`           | string  | Oui    | -          | Le handle `vv_...` retourné par `POST /audio/voices`                                                  |
| `input`           | string  | Oui    | -          | Texte à synthétiser, jusqu'à 4096 caractères                                                          |
| `response_format` | string  | Non    | `mp3`      | `mp3`, `opus`, `aac`, `flac`, `wav` ou `pcm`                                                          |
| `speed`           | number  | Non    | `1`        | Vitesse de parole de `0.25` à `4.0`                                                                   |
| `temperature`     | number  | Non    | -          | Température d'échantillonnage de `0` à `2`. Des valeurs plus élevées peuvent ajouter de la variation. |
| `streaming`       | boolean | Non    | `false`    | Diffuser l'audio phrase par phrase                                                                    |

## Erreurs courantes

| Statut | Cause                                                             | Solution                                                                                             |
| ------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `400`  | Conteneur audio non pris en charge ou handle de voix incompatible | Utilisez MP3, WAV, FLAC ou M4A et associez le handle au même modèle que celui utilisé pour le créer. |
| `401`  | Clé API manquante ou invalide                                     | Envoyez `Authorization: Bearer $VENICE_API_KEY`.                                                     |
| `402`  | Solde insuffisant                                                 | Rechargez votre solde Venice.                                                                        |
| `413`  | Le fichier téléversé est trop volumineux                          | Utilisez un échantillon de référence plus court ou plus compressé.                                   |
| `429`  | Limite de débit dépassée                                          | Réessayez après la réinitialisation de la fenêtre de limite de débit.                                |