Guia de clonagem de voz | Documentação da API 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.

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

Como funciona

Envie - Envie um arquivo de áudio de referência limpo para POST /audio/voices
Salve - Armazene o handle de voz id retornado
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 MP4
Pelo menos 5 a 10 segundos de fala clara de um único locutor

Defina sua chave de API:

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:

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"

Ao usar curl -F, não defina Content-Type manualmente. O curl adiciona o cabeçalho multipart/form-data e o boundary necessário. Resposta (200):

{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}

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

export VENICE_VOICE_ID="vv_voice_abc123xyz"

Etapa 2: gerar fala

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

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

O corpo da resposta é áudio binário no formato padrão do modelo, e não JSON. Atualmente, o tts-chatterbox-hd usa WAV como padrão.

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.wav:

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

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:

curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"

O tts-chatterbox-hd informa:

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

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	Específico do modelo	Substituição opcional do formato de saída. Verifique os formatos suportados e o padrão do modelo antes de defini-lo.
`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

A resposta de fala bem-sucedida é áudio binário, e seu Content-Type identifica o formato retornado. Você pode omitir response_format para usar o padrão do modelo. Consulte model_spec.supported_formats e model_spec.default_format em GET /models?type=tts antes de substituí-lo; solicitar um formato não suportado retorna HTTP 400.

Erros comuns

Status	Causa	Correção
`400`	Container de áudio não suportado ou handle de voz incompatível	Use MP3, WAV, FLAC ou MP4 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.

Documentação

Primeiros passos

Texto e chat

Imagem, vídeo e áudio

Pesquisa e RAG

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

Clonagem de voz

Como funciona

Pré-requisitos

Etapa 1: enviar uma amostra de voz

Etapa 2: gerar fala

Exemplo completo

Dicas para a amostra de voz

Expiração do handle

Descobrir suporte a clonagem

Parâmetros da API

Criar voz

Gerar fala

Erros comuns

​Como funciona

​Pré-requisitos

​Etapa 1: enviar uma amostra de voz

​Etapa 2: gerar fala

​Exemplo completo

​Dicas para a amostra de voz

​Expiração do handle

​Descobrir suporte a clonagem

​Parâmetros da API

​Criar voz

​Gerar fala

​Erros comuns

Como funciona

Pré-requisitos

Etapa 1: enviar uma amostra de voz

Etapa 2: gerar fala

Exemplo completo

Dicas para a amostra de voz

Expiração do handle

Descobrir suporte a clonagem

Parâmetros da API

Criar voz

Gerar fala

Erros comuns