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

# Clonagem de voz

> Clone uma voz a partir de uma pequena amostra de áudio de referência com o Chatterbox HD e gere fala pela API de áudio da Venice.

A clonagem de voz permite gerar fala em uma voz fornecida por uma pequena amostra de áudio de referência. Com `tts-chatterbox-hd`, envie uma amostra para `/audio/voices`, salve o handle de voz `vv_...` retornado e, em seguida, passe esse handle para `/audio/speech`.

<Note>
  Os handles de voz são específicos do modelo. Um handle criado com `tts-chatterbox-hd` deve ser usado com `tts-chatterbox-hd`.
</Note>

## Como funciona

1. **Envie** - Envie um arquivo de áudio de referência limpo para `POST /audio/voices`
2. **Salve** - Armazene o handle de voz `id` retornado
3. **Gere** - Envie o handle como `voice` em `POST /audio/speech`

## Pré-requisitos

* Uma chave de API da Venice
* Uma amostra de referência limpa nos formatos MP3, WAV, FLAC ou M4A
* Pelo menos 5 a 10 segundos de fala clara de um único locutor

Defina sua chave de API:

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

## Etapa 1: enviar uma amostra de voz

Crie um handle de voz enviando o áudio de referência como multipart form data:

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

**Resposta (200):**

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

Salve o `id` para a geração de fala:

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

## Etapa 2: gerar fala

Passe o handle de voz clonada como `voice` na requisição de fala:

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

O corpo da resposta é áudio binário no formato solicitado.

***

## Exemplo completo

Este exemplo envia uma amostra de referência, extrai o handle de voz com `jq` e grava o áudio gerado em `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
```

## Dicas para a amostra de voz

Use uma amostra com um único locutor, ruído de fundo mínimo e sem música. A fala natural funciona melhor do que áudio sussurrado, cantado ou muito processado.

Amostras mais longas podem ajudar quando a voz tem ritmo, sotaque ou tom distintos, mas mantenha a amostra focada no locutor-alvo.

## Expiração do handle

A clonagem no Chatterbox HD é zero-shot: a Venice armazena o áudio de referência enviado temporariamente, e o modelo o lê quando você sintetiza fala. Nenhum template de voz persistente é criado.

Os handles de voz expiram automaticamente após 7 dias. Depois que um handle expira, envie a amostra de referência novamente para criar um novo handle `vv_...`.

## Descobrir suporte a clonagem

Modelos que suportam clonagem incluem um objeto `voice_cloning` na especificação do modelo. Consulte os modelos de TTS para verificar os formatos suportados, o tamanho mínimo da amostra e a retenção:

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

O `tts-chatterbox-hd` informa:

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

***

## Parâmetros da API

### Criar voz

| Campo   | Tipo   | Obrigatório | Descrição                                                                        |
| ------- | ------ | ----------- | -------------------------------------------------------------------------------- |
| `model` | string | Sim         | Deve ser `tts-chatterbox-hd`                                                     |
| `file`  | file   | Sim         | Amostra de áudio de referência. Os formatos suportados são MP3, WAV, FLAC e M4A. |

### Gerar fala

| Campo             | Tipo    | Obrigatório | Padrão  | Descrição                                                                            |
| ----------------- | ------- | ----------- | ------- | ------------------------------------------------------------------------------------ |
| `model`           | string  | Sim         | -       | Deve corresponder ao modelo usado para criar o handle de voz                         |
| `voice`           | string  | Sim         | -       | O handle `vv_...` retornado por `POST /audio/voices`                                 |
| `input`           | string  | Sim         | -       | Texto a sintetizar, com até 4096 caracteres                                          |
| `response_format` | string  | Não         | `mp3`   | `mp3`, `opus`, `aac`, `flac`, `wav` ou `pcm`                                         |
| `speed`           | number  | Não         | `1`     | Velocidade da fala de `0.25` a `4.0`                                                 |
| `temperature`     | number  | Não         | -       | Temperatura de amostragem de `0` a `2`. Valores mais altos podem adicionar variação. |
| `streaming`       | boolean | Não         | `false` | Transmite o áudio sentença por sentença                                              |

## Erros comuns

| Status | Causa                                                          | Correção                                                                            |
| ------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `400`  | Container de áudio não suportado ou handle de voz incompatível | Use MP3, WAV, FLAC ou M4A e combine o handle com o mesmo modelo usado para criá-lo. |
| `401`  | Chave de API ausente ou inválida                               | Envie `Authorization: Bearer $VENICE_API_KEY`.                                      |
| `402`  | Saldo insuficiente                                             | Recarregue seu saldo na Venice.                                                     |
| `413`  | O arquivo enviado é muito grande                               | Use uma amostra de referência mais curta ou mais comprimida.                        |
| `429`  | Limite de requisições excedido                                 | Tente novamente após o reinício da janela de limite de requisições.                 |