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

# Clonación de voz

> Clona una voz a partir de una muestra de audio de referencia corta con Chatterbox HD y luego genera voz a través de la API de audio de Venice.

La clonación de voz te permite generar voz utilizando una voz proporcionada por una muestra de audio de referencia corta. Con `tts-chatterbox-hd`, sube una muestra a `/audio/voices`, guarda el identificador de voz `vv_...` devuelto y luego pásalo a `/audio/speech`.

<Note>
  Los identificadores de voz son específicos del modelo. Un identificador creado con `tts-chatterbox-hd` debe usarse con `tts-chatterbox-hd`.
</Note>

## Cómo funciona

1. **Subir** - Envía un archivo de audio de referencia limpio a `POST /audio/voices`
2. **Guardar** - Almacena el identificador de voz `id` devuelto
3. **Generar** - Envía el identificador como `voice` en `POST /audio/speech`

## Requisitos previos

* Una clave de API de Venice
* Una muestra de referencia limpia en formato MP3, WAV, FLAC o M4A
* Al menos de 5 a 10 segundos de voz clara de un solo hablante

Configura tu clave de API:

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

## Paso 1: Sube una muestra de voz

Crea un identificador de voz subiendo el audio de referencia como datos de formulario 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"
```

**Respuesta (200):**

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

Guarda el `id` para la generación de voz:

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

## Paso 2: Genera voz

Pasa el identificador de voz clonada como `voice` en la solicitud de voz:

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

El cuerpo de la respuesta es audio binario en el formato solicitado.

***

## Ejemplo completo

Este ejemplo sube una muestra de referencia, extrae el identificador de voz con `jq` y escribe el audio generado en `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
```

## Consejos para la muestra de voz

Usa una muestra con un solo hablante, mínimo ruido de fondo y sin música. El habla natural funciona mejor que el audio susurrado, cantado o muy procesado.

Las muestras más largas pueden ayudar cuando la voz tiene un ritmo, acento o tono distintivos, pero mantén la muestra centrada en el hablante objetivo.

## Caducidad del identificador

La clonación de Chatterbox HD es zero-shot: Venice almacena temporalmente el audio de referencia subido y el modelo lo lee cuando sintetizas voz. No se crea ninguna plantilla de voz persistente.

Los identificadores de voz caducan automáticamente después de 7 días. Cuando un identificador caduca, vuelve a subir la muestra de referencia para crear un nuevo identificador `vv_...`.

## Detectar compatibilidad con la clonación

Los modelos que admiten clonación incluyen un objeto `voice_cloning` en la especificación del modelo. Consulta los modelos TTS para comprobar los formatos admitidos, la duración mínima de la muestra y la retención:

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

`tts-chatterbox-hd` indica:

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

***

## Parámetros de la API

### Crear voz

| Campo   | Tipo   | Obligatorio | Descripción                                                                      |
| ------- | ------ | ----------- | -------------------------------------------------------------------------------- |
| `model` | string | Sí          | Debe ser `tts-chatterbox-hd`                                                     |
| `file`  | file   | Sí          | Muestra de audio de referencia. Los formatos admitidos son MP3, WAV, FLAC y M4A. |

### Generar voz

| Campo             | Tipo    | Obligatorio | Predeterminado | Descripción                                                                                 |
| ----------------- | ------- | ----------- | -------------- | ------------------------------------------------------------------------------------------- |
| `model`           | string  | Sí          | -              | Debe coincidir con el modelo usado para crear el identificador de voz                       |
| `voice`           | string  | Sí          | -              | El identificador `vv_...` devuelto por `POST /audio/voices`                                 |
| `input`           | string  | Sí          | -              | Texto a sintetizar, hasta 4096 caracteres                                                   |
| `response_format` | string  | No          | `mp3`          | `mp3`, `opus`, `aac`, `flac`, `wav` o `pcm`                                                 |
| `speed`           | number  | No          | `1`            | Velocidad del habla desde `0.25` hasta `4.0`                                                |
| `temperature`     | number  | No          | -              | Temperatura de muestreo desde `0` hasta `2`. Los valores más altos pueden añadir variación. |
| `streaming`       | boolean | No          | `false`        | Transmite el audio frase por frase                                                          |

## Errores comunes

| Estado | Causa                                                               | Solución                                                                                     |
| ------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `400`  | Contenedor de audio no admitido o identificador de voz incompatible | Usa MP3, WAV, FLAC o M4A y empareja el identificador con el mismo modelo usado para crearlo. |
| `401`  | Clave de API ausente o no válida                                    | Envía `Authorization: Bearer $VENICE_API_KEY`.                                               |
| `402`  | Saldo insuficiente                                                  | Recarga tu saldo de Venice.                                                                  |
| `413`  | El archivo subido es demasiado grande                               | Usa una muestra de referencia más corta o más comprimida.                                    |
| `429`  | Límite de tasa superado                                             | Reintenta después de que se reinicie la ventana del límite de tasa.                          |