--- title: "Clonagem de Voz" description: "Cria uma voz própria a partir de amostras de áudio, para usar nas APIs de fala. Preço por faixa, a partir de R$ 9,90 por chamada. Disponível para contas PJ." lang: pt-BR canonical: https://doc.apibrasil.io/apis/creditos/360c9e36-dec0-11f1-98bb-bc24118aba26 markdown: https://doc.apibrasil.io/apis/creditos/360c9e36-dec0-11f1-98bb-bc24118aba26.md source: apibrasil-documentation --- # Clonagem de Voz > Cria uma voz própria a partir de amostras de áudio, para usar nas APIs de fala. Preço por faixa, a partir de R$ 9,90 por chamada. Disponível para contas PJ. - **Categoria:** Voz e Áudio com IA - **Cobrança:** por consulta, só com o Bearer Token - **Preço:** R$ 9,90 por consulta - **Limite:** 990.000 por mês - **Cadastro:** exige CNPJ - **Versão:** v2 - **Publicada por:** APIBrasil - **Especificação OpenAPI:** https://doc.apibrasil.io/apis/creditos/360c9e36-dec0-11f1-98bb-bc24118aba26/openapi.json ## Como chamar **Endereço base:** `https://gateway.apibrasil.io/api/v2` Autenticação: cabeçalho `Authorization: Bearer `. Nada além disso. Com `homolog: true` no corpo, o gateway responde de uma base fixa, com a forma real da resposta, e não cobra. O CPF 00000000000 é dessa base e não é de ninguém: use-o nos testes, nunca em produção. ## Endpoints (4 endpoints) **Sumário** 1. `POST /consulta/voz-clonagem/credits` 2. `POST /consulta/voz-clonagem/credits` 3. `POST /consulta/voz-clonagem/credits` 4. `POST /consulta/voz-clonagem/credits` ### 1. POST /consulta/voz-clonagem/credits ⚠️ Aviso: a chamada é cobrada (R$ 9,90) quando a voz é criada e fica disponível para a conta (HTTP 200). Campo inválido, amostra fora do tamanho ou em formato não aceito, conta no limite de vozes, voz protegida e falha na criação não são cobrados. Criar voz a partir de amostras: Cria uma voz própria a partir de 1 a 3 gravações da voz de uma mesma pessoa, cada uma com 10 segundos a 3 minutos e todas somadas com até 3 minutos (até 1 minuto e meio com remover_ruido), e devolve o identificador da voz (voz). Esse identificador passa a valer no campo voz das APIs de fala da sua conta, e só da sua conta. A resposta traz também o nome gravado, quantas vozes próprias a conta tem agora (vozes_da_conta) e o limite da conta (limite_de_vozes). O resultado é melhor com gravação limpa, sem música nem outras pessoas falando, e com 1 a 3 minutos de fala no total. Envie um POST com tipo=voz-clonagem-criar e: - nome_da_voz (obrigatório, texto): Nome da voz, de 3 a 60 caracteres. É como ela aparece nas listas de vozes da sua conta. - amostras (opcional, lista): De 1 a 3 gravações da mesma pessoa. Cada item é um objeto com audio_url (link público do arquivo, de até 25 MB) ou audio_base64 (o arquivo em base64, de até 1 MiB depois de decodificado), nunca os dois. Formatos aceitos: MP3, Ogg/Opus ou WAV sem compressão (PCM); FLAC, M4A/AAC, Ogg/Vorbis, WebM e vídeo são recusados, sem cobrança. Cada gravação precisa ter de 10 segundos a 3 minutos, e todas somadas, até 3 minutos (até 1 minuto e meio com remover_ruido). Obrigatório quando os campos audio_url e audio_base64 não são usados. - audio_url (opcional, url): Atalho para uma gravação só: o link público do arquivo. Use no lugar do campo amostras, nunca junto com ele. - audio_base64 (opcional, base64): Atalho para uma gravação só: o arquivo em base64, de até 1 MiB depois de decodificado. Use no lugar do campo amostras, nunca junto com ele. - titular (obrigatório, texto): Nome completo da pessoa dona da voz gravada, de 3 a 120 caracteres. - declaro_autorizacao (obrigatório, booleano): Precisa ser true. Com ele você declara que o titular é maior de 18 anos, autorizou de forma expressa a criação e o uso desta voz e que você guarda a prova dessa autorização. - descricao_da_voz (opcional, texto): Anotação livre sobre a voz, de até 300 caracteres. Volta na lista de vozes da conta. - sexo (opcional, texto): feminino, masculino ou neutro. Aparece na lista de vozes das APIs de fala e serve de filtro lá. - remover_ruido (opcional, booleano): true para limpar o ruído de fundo das gravações antes de criar a voz. Em gravação que já está limpa pode piorar o resultado. Com a limpeza, as gravações somadas podem ter até 1 minuto e meio, e as enviadas por link precisam chegar mais depressa, porque a limpeza também toma tempo. Padrão: false. Respostas de erro (nenhuma é cobrada): - HTTP 400: campo obrigatório ausente ou fora do tamanho, declaro_autorizacao diferente de true, nenhuma amostra ou mais de 3, amostra em formato não aceito (FLAC, M4A/AAC, Ogg/Vorbis, WebM ou vídeo) ou com menos de 10 segundos ou mais de 3 minutos (a mensagem diz qual amostra e o motivo), gravações que somam mais de 3 minutos (ou mais de 1 minuto e meio com remover_ruido) - HTTP 422: a conta já está no limite de vozes próprias; remova uma voz para criar outra (a resposta traz vozes_da_conta e limite_de_vozes). Repetir o pedido não adianta - HTTP 422: a amostra corresponde a uma voz protegida e não pode ser clonada - HTTP 502: o serviço de voz respondeu sem a voz criada ou com erro - HTTP 503: no momento não há vaga para criar novas vozes; tente de novo mais tarde - HTTP 503: o serviço de voz está indisponível ou no limite de chamadas simultâneas; tente de novo em alguns minutos - HTTP 504: o download das amostras ou a criação da voz passou do tempo limite; amostras por link precisam chegar em poucos segundos: uns 25 segundos ao todo, ou uns 10 com remover_ruido e 1 minuto e meio de gravação, porque a limpeza também toma tempo (prefira audio_base64 para arquivos grandes) Preço: R$ 9,90 por chamada. Disponível para contas PJ. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. Só envie gravações de quem autorizou. Clonar a voz de uma pessoa sem a autorização expressa dela, a voz de menor de 18 anos ou a voz de figura pública é proibido. A cada criação você informa o titular da voz e declara que tem a autorização; guarde a prova (termo assinado ou gravação do consentimento) por 5 anos, porque ela pode ser pedida. Amostra que corresponde a uma voz protegida é recusada: a voz não é criada e a chamada não é cobrada. As gravações enviadas e a voz criada são processadas e guardadas em servidores nos Estados Unidos. Não envie gravação com dado de saúde, número de cartão ou número de documento oficial, como o CPF. O áudio gerado com uma voz clonada leva uma marca d'água inaudível, que não pode ser removida. Avise quem ouve que a voz é sintética quando a lei exigir ou quando a falta do aviso puder enganar. - **Método:** `POST` - **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits` - **Versão da rota:** v2 **Cabeçalhos** | Cabeçalho | Valor | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Corpo da requisição** ```json { "tipo": "voz-clonagem-criar", "nome_da_voz": "Locutora da loja", "amostras": [ { "audio_url": "https://exemplo.com.br/amostra-1.mp3" }, { "audio_url": "https://exemplo.com.br/amostra-2.mp3" } ], "sexo": "feminino", "titular": "Ana Paula de Souza", "declaro_autorizacao": true, "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-clonagem-criar","nome_da_voz":"Locutora da loja","amostras":[{"audio_url":"https://exemplo.com.br/amostra-1.mp3"},{"audio_url":"https://exemplo.com.br/amostra-2.mp3"}],"sexo":"feminino","titular":"Ana Paula de Souza","declaro_autorizacao":true,"homolog":true}' ``` Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação. **Resposta de exemplo, do catálogo** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "390,100", "balance_before": "400,000", "tax": "9,900", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 9,90.", "valor_consulta": 9.9, "api_limit_for": "credit", "homolog": false, "data": { "tipo": "voz-clonagem-criar", "voz": "AbCdEfGhIj0123456789", "nome_da_voz": "Locutora da loja", "vozes_da_conta": 1, "limite_de_vozes": 3 } } ``` ### 2. POST /consulta/voz-clonagem/credits ⚠️ Aviso: a chamada é cobrada (R$ 0,01) quando a lista é devolvida (HTTP 200), mesmo que a conta ainda não tenha voz. Falha na consulta não é cobrada. Listar as vozes da conta: Lista as vozes próprias da sua conta, tanto as clonadas quanto as criadas por descrição. Cada voz traz o identificador (voz, o valor do campo voz nas APIs de fala), o nome, o tipo (clonada ou criada), a data de criação (criada_em) e a anotação gravada (descricao_da_voz). A resposta traz também o total de vozes e o limite da conta (limite_de_vozes). Não tem campos de entrada além do tipo. Envie um POST só com tipo=voz-clonagem-vozes. Respostas de erro (nenhuma é cobrada): - HTTP 502: o serviço de voz respondeu fora do esperado - HTTP 503: o serviço de voz está indisponível ou no limite de chamadas simultâneas; tente de novo em alguns minutos - HTTP 504: o serviço de voz não respondeu dentro do tempo limite Preço: R$ 0,01 por chamada. Disponível para contas PJ. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. Só envie gravações de quem autorizou. Clonar a voz de uma pessoa sem a autorização expressa dela, a voz de menor de 18 anos ou a voz de figura pública é proibido. A cada criação você informa o titular da voz e declara que tem a autorização; guarde a prova (termo assinado ou gravação do consentimento) por 5 anos, porque ela pode ser pedida. Amostra que corresponde a uma voz protegida é recusada: a voz não é criada e a chamada não é cobrada. As gravações enviadas e a voz criada são processadas e guardadas em servidores nos Estados Unidos. Não envie gravação com dado de saúde, número de cartão ou número de documento oficial, como o CPF. O áudio gerado com uma voz clonada leva uma marca d'água inaudível, que não pode ser removida. Avise quem ouve que a voz é sintética quando a lei exigir ou quando a falta do aviso puder enganar. - **Método:** `POST` - **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits` - **Versão da rota:** v2 **Cabeçalhos** | Cabeçalho | Valor | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Corpo da requisição** ```json { "tipo": "voz-clonagem-vozes", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-clonagem-vozes","homolog":true}' ``` Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação. **Resposta de exemplo, do catálogo** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,990", "balance_before": "400,000", "tax": "0,010", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,01.", "valor_consulta": 0.01, "api_limit_for": "credit", "homolog": false, "data": { "tipo": "voz-clonagem-vozes", "vozes": [ { "voz": "AbCdEfGhIj0123456789", "nome": "Locutora da loja", "tipo": "clonada", "criada_em": "2026-11-10T09:30:00-03:00", "descricao_da_voz": "Voz da Ana, usada nos avisos de entrega" }, { "voz": "KlMnOpQrSt9876543210", "nome": "Narrador institucional", "tipo": "criada", "criada_em": "2026-11-12T10:00:00-03:00", "descricao_da_voz": "Voz masculina, adulta, grave e calma, com sotaque paulistano." } ], "total": 2, "limite_de_vozes": 3 } } ``` ### 3. POST /consulta/voz-clonagem/credits ⚠️ Aviso: a chamada é cobrada (R$ 0,49) quando a alteração é gravada (HTTP 200). Campo inválido, voz que não é da sua conta e falha na gravação não são cobrados. Alterar nome, descrição e ajustes de uma voz da conta: Altera o nome, a anotação ou os ajustes (estabilidade e similaridade) gravados em uma voz própria da sua conta. Informe a voz e ao menos um dos outros campos; o que não for enviado fica como está. Devolve a voz com os valores gravados depois da alteração. Envie um POST com tipo=voz-clonagem-configurar e: - voz (obrigatório, texto): O identificador de uma voz própria da sua conta, tirado da lista de vozes da conta. - nome_da_voz (opcional, texto): Novo nome da voz, de 3 a 60 caracteres. - descricao_da_voz (opcional, texto): Nova anotação sobre a voz, de até 300 caracteres. - estabilidade (opcional, decimal): De 0 a 1. Estabilidade gravada na voz: mais alta deixa a fala mais constante; mais baixa, mais expressiva. O valor enviado no próprio pedido de fala tem prioridade sobre o gravado aqui. - similaridade (opcional, decimal): De 0 a 1. Similaridade gravada na voz: o quanto a fala se prende ao timbre das amostras. O valor enviado no próprio pedido de fala tem prioridade sobre o gravado aqui. Respostas de erro (nenhuma é cobrada): - HTTP 400: voz ausente ou fora do padrão, nenhum campo para alterar, ou nome, anotação, estabilidade ou similaridade fora do tamanho ou da faixa - HTTP 404: a voz não existe ou não é uma voz própria da sua conta (vozes do catálogo não podem ser alteradas) - HTTP 502: o serviço de voz respondeu sem confirmar a alteração ou com erro - HTTP 503: o serviço de voz está indisponível ou no limite de chamadas simultâneas; tente de novo em alguns minutos - HTTP 504: o serviço de voz não respondeu dentro do tempo limite Preço: R$ 0,49 por chamada. Disponível para contas PJ. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. Só envie gravações de quem autorizou. Clonar a voz de uma pessoa sem a autorização expressa dela, a voz de menor de 18 anos ou a voz de figura pública é proibido. A cada criação você informa o titular da voz e declara que tem a autorização; guarde a prova (termo assinado ou gravação do consentimento) por 5 anos, porque ela pode ser pedida. Amostra que corresponde a uma voz protegida é recusada: a voz não é criada e a chamada não é cobrada. As gravações enviadas e a voz criada são processadas e guardadas em servidores nos Estados Unidos. Não envie gravação com dado de saúde, número de cartão ou número de documento oficial, como o CPF. O áudio gerado com uma voz clonada leva uma marca d'água inaudível, que não pode ser removida. Avise quem ouve que a voz é sintética quando a lei exigir ou quando a falta do aviso puder enganar. - **Método:** `POST` - **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits` - **Versão da rota:** v2 **Cabeçalhos** | Cabeçalho | Valor | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Corpo da requisição** ```json { "tipo": "voz-clonagem-configurar", "voz": "AbCdEfGhIj0123456789", "nome_da_voz": "Locutora da matriz", "estabilidade": 0.6, "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-clonagem-configurar","voz":"AbCdEfGhIj0123456789","nome_da_voz":"Locutora da matriz","estabilidade":0.6,"homolog":true}' ``` Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação. **Resposta de exemplo, do catálogo** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,510", "balance_before": "400,000", "tax": "0,490", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,49.", "valor_consulta": 0.49, "api_limit_for": "credit", "homolog": false, "data": { "tipo": "voz-clonagem-configurar", "voz": "AbCdEfGhIj0123456789", "nome_da_voz": "Locutora da matriz", "descricao_da_voz": "Voz da Ana, usada nos avisos de entrega", "estabilidade": 0.6, "similaridade": 0.75 } } ``` ### 4. POST /consulta/voz-clonagem/credits ⚠️ Aviso: a chamada é cobrada (R$ 0,01) quando a voz é removida (HTTP 200). Voz que não é da sua conta e falha na remoção não são cobradas. Remover uma voz da conta: Remove uma voz própria da sua conta e libera a vaga para criar outra. A remoção é definitiva: o identificador deixa de valer no campo voz das APIs de fala e a voz não pode ser recuperada. Devolve a voz removida e a situação. Envie um POST com tipo=voz-clonagem-remover e: - voz (obrigatório, texto): O identificador de uma voz própria da sua conta, tirado da lista de vozes da conta. Respostas de erro (nenhuma é cobrada): - HTTP 400: campo voz ausente ou fora do padrão (10 a 40 letras e dígitos) - HTTP 404: a voz não existe ou não é uma voz própria da sua conta (vozes do catálogo não podem ser removidas) - HTTP 502: o serviço de voz respondeu sem confirmar a remoção ou com erro - HTTP 503: o serviço de voz está indisponível ou no limite de chamadas simultâneas; tente de novo em alguns minutos - HTTP 504: o serviço de voz não respondeu dentro do tempo limite Preço: R$ 0,01 por chamada. Disponível para contas PJ. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. Só envie gravações de quem autorizou. Clonar a voz de uma pessoa sem a autorização expressa dela, a voz de menor de 18 anos ou a voz de figura pública é proibido. A cada criação você informa o titular da voz e declara que tem a autorização; guarde a prova (termo assinado ou gravação do consentimento) por 5 anos, porque ela pode ser pedida. Amostra que corresponde a uma voz protegida é recusada: a voz não é criada e a chamada não é cobrada. As gravações enviadas e a voz criada são processadas e guardadas em servidores nos Estados Unidos. Não envie gravação com dado de saúde, número de cartão ou número de documento oficial, como o CPF. O áudio gerado com uma voz clonada leva uma marca d'água inaudível, que não pode ser removida. Avise quem ouve que a voz é sintética quando a lei exigir ou quando a falta do aviso puder enganar. - **Método:** `POST` - **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits` - **Versão da rota:** v2 **Cabeçalhos** | Cabeçalho | Valor | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Corpo da requisição** ```json { "tipo": "voz-clonagem-remover", "voz": "AbCdEfGhIj0123456789", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-clonagem/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-clonagem-remover","voz":"AbCdEfGhIj0123456789","homolog":true}' ``` Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação. **Resposta de exemplo, do catálogo** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "399,990", "balance_before": "400,000", "tax": "0,010", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,01.", "valor_consulta": 0.01, "api_limit_for": "credit", "homolog": false, "data": { "tipo": "voz-clonagem-remover", "voz": "AbCdEfGhIj0123456789", "situacao": "removida" } } ``` Nos exemplos de resposta, os campos da conta que gerou o exemplo (`user.first_name`, `user.email`, `user.cellphone`) saem como `[omitido]`. O resto é o que o catálogo publica. ## Armadilhas: o que uma integração erra sem avisar Apuradas nas respostas que o próprio catálogo publica. Em todas elas o código funciona no caminho feliz e falha em silêncio no resto: 1. **O erro chega no CORPO, com HTTP 200.** A resposta traz um campo `error` booleano e uma `message`. Checar só `response.ok` ou o status HTTP deixa passar falha como sucesso. Confira SEMPRE `error === false` antes de ler `data`. 2. **`balance`, `tax` e `extra_charges.total` são STRING em formato brasileiro — e o formato varia entre APIs.** Valores observados no catálogo: `"154,380"`, `"497,84"`, `"0,000"` e `"0.19"`. Vírgula em umas, ponto em outra; três casas decimais em umas, duas em outra. Em JavaScript, `parseFloat("154,380")` devolve `154` e perde os centavos sem erro nenhum, e `Number("154,380")` devolve `NaN`. Escreva um conversor que trate os dois separadores, e nunca use esses campos numa decisão financeira sem convertê-los. 3. **Cada chamada custa dinheiro.** Retry cego multiplica a conta. Nunca repita automaticamente um 4xx: parâmetro errado repetido continua errado e continua cobrando. Repita só tempo esgotado e 5xx, com recuo exponencial e um teto pequeno de tentativas. 4. **HTTP 402 é saldo insuficiente, e repetir não resolve.** É o único status que exige ação humana — recarregar. Trate-o como erro terminal, com mensagem própria, e não o jogue no mesmo balde dos 4xx genéricos. 5. **`extra_charges` cobra à parte do preço da consulta.** Quando o corpo pede serviços adicionais, a resposta traz cada um com o preço e um `total` que NÃO está incluso no valor base. Se você mostra custo a quem usa, some os dois. ## Ver também - Especificação OpenAPI: https://doc.apibrasil.io/apis/creditos/360c9e36-dec0-11f1-98bb-bc24118aba26/openapi.json - Catálogo de APIs: [Catálogo de APIs](https://doc.apibrasil.io/apis.md) - SDKs oficiais: [SDKs oficiais](https://doc.apibrasil.io/sdks.md) - Índice da documentação: https://doc.apibrasil.io/llms.txt - Versão HTML desta página: https://doc.apibrasil.io/apis/creditos/360c9e36-dec0-11f1-98bb-bc24118aba26