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

# Clonación de voz

> Clona una voz desde una muestra de audio corta con Chatterbox HD, guarda el identificador devuelto y genera voz con la API de Audio de Venice.

La clonación de voz te permite generar voz en 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`. La clonación de voz es texto a voz a partir de una muestra de referencia. Para volver a grabar una grabación existente en otra voz, usa la API de [Voice Changer](/es/guides/media/voice-changer) en su lugar.
</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 MP4
* Al menos de 5 a 10 segundos de voz clara de un solo hablante

Configura tu clave de API:

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

Cuando uses `curl -F`, no establezcas `Content-Type` manualmente. `curl` añade el encabezado `multipart/form-data` y el delimitador requerido.

**Respuesta (200):**

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

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

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

El cuerpo de la respuesta es audio binario en el formato predeterminado del modelo, no JSON. Actualmente `tts-chatterbox-hd` usa WAV de forma predeterminada.

***

## Ejemplo completo

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

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

`tts-chatterbox-hd` indica:

```json theme={null}
{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "mp4"],
    "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 MP4. |

### 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 | Específico del modelo | Anulación opcional del formato de salida. Comprueba los formatos admitidos y el predeterminado del modelo antes de establecerlo. |
| `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 |

La respuesta correcta de voz es audio binario y su `Content-Type` identifica el formato devuelto. Puedes omitir `response_format` para usar el predeterminado del modelo. Consulta `model_spec.supported_formats` y `model_spec.default_format` desde `GET /models?type=tts` antes de anularlo; solicitar un formato no admitido devuelve HTTP `400`.

## Errores comunes

| Estado | Causa | Solución |
| - | - | - |
| `400` | Contenedor de audio no admitido o identificador de voz incompatible | Usa MP3, WAV, FLAC o MP4 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. |


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