--- title: "Criação de Voz por Descrição" description: "Descreva a voz que você quer (sexo, idade, tom, sotaque) e receba prévias para escolher e salvar. Preço por faixa, a partir de R$ 0,75 por chamada." lang: pt-BR canonical: https://doc.apibrasil.io/apis/creditos/360ca585-dec0-11f1-98bb-bc24118aba26 markdown: https://doc.apibrasil.io/apis/creditos/360ca585-dec0-11f1-98bb-bc24118aba26.md source: apibrasil-documentation --- # Criação de Voz por Descrição > Descreva a voz que você quer (sexo, idade, tom, sotaque) e receba prévias para escolher e salvar. Preço por faixa, a partir de R$ 0,75 por chamada. - **Categoria:** Voz e Áudio com IA - **Cobrança:** por consulta, só com o Bearer Token - **Preço:** R$ 0,75 por consulta - **Limite:** 990.000 por mês - **Cadastro:** CPF ou CNPJ - **Versão:** v2 - **Publicada por:** APIBrasil - **Especificação OpenAPI:** https://doc.apibrasil.io/apis/creditos/360ca585-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-criacao-por-descricao/credits` 2. `POST /consulta/voz-criacao-por-descricao/credits` 3. `POST /consulta/voz-criacao-por-descricao/credits` 4. `POST /consulta/voz-criacao-por-descricao/credits` ### 1. POST /consulta/voz-criacao-por-descricao/credits ⚠️ Aviso: a chamada é cobrada (R$ 0,75) quando as 3 prévias são devolvidas com áudio (HTTP 200). Descrição ou texto fora do tamanho, conteúdo barrado pela moderação e falha na geração não são cobrados. Gerar 3 prévias de voz a partir da descrição: Gera 3 prévias de uma voz nova a partir da descrição. Cada prévia traz o identificador dela (previa), o link de um áudio em que a voz lê o texto de amostra (audio_url), o tipo do arquivo, o tamanho, a duração e a validade do link. A resposta traz também o total de prévias e quantos caracteres o texto de amostra tem. O texto de amostra pode ter de 100 a 300 caracteres; sem ele, a voz lê um texto padrão em português. Quanto mais detalhada a descrição, mais perto do pedido a voz fica. Envie um POST com tipo=voz-criacao-por-descricao-previas e: - descricao_da_voz (obrigatório, texto): Como a voz deve ser, de 20 a 1000 caracteres: sexo, idade, tom, sotaque, ritmo e o uso que ela vai ter. - texto (opcional, texto): O que a voz lê nas prévias: de 100 a 300 caracteres. Sem este campo, as prévias leem um texto padrão em português. - variacao (opcional, inteiro): Opcional e sem efeito, de 0 a 999999: cada pedido já gera prévias novas e é cobrado, mesmo com o corpo igual ao de um pedido anterior. Aceito por compatibilidade com as outras APIs de voz. Respostas de erro (nenhuma é cobrada): - HTTP 400: descrição ausente ou fora de 20 a 1000 caracteres, texto fora de 100 a 300 caracteres ou variacao fora de 0 a 999999 - HTTP 422: a descrição ou o texto foi barrado pela moderação do serviço de voz - HTTP 502: o serviço de voz respondeu sem as 3 prévias com áudio 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: a geração das prévias passou do tempo limite Preço: R$ 0,75 por chamada. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. A prévia é provisória: salve a escolhida logo depois de gerar. Só a conta que gerou a prévia pode salvá-la, em até 24 horas. Prévia que já expirou é recusada sem cobrança, e é preciso gerar outras. A descrição e o texto de amostra são processados em servidores nos Estados Unidos. Não envie neles dado de saúde, número de cartão ou número de documento oficial, como o CPF. Não descreva a voz de uma pessoa real nem peça a imitação de alguém: este produto cria vozes novas. Para a voz de uma pessoa, com a autorização dela, use a API de Clonagem de Voz. O áudio gerado com a voz criada 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-criacao-por-descricao/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-criacao-por-descricao-previas", "descricao_da_voz": "Voz feminina, adulta, tom acolhedor e calmo, sotaque paulistano, ritmo pausado, para atendimento.", "texto": "Olá! Aqui é a central de atendimento. Seu pedido foi confirmado, sai para entrega amanhã cedo e chega até as 18 horas.", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-criacao-por-descricao/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-criacao-por-descricao-previas","descricao_da_voz":"Voz feminina, adulta, tom acolhedor e calmo, sotaque paulistano, ritmo pausado, para atendimento.","texto":"Olá! Aqui é a central de atendimento. Seu pedido foi confirmado, sai para entrega amanhã cedo e chega até as 18 horas.","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,250", "balance_before": "400,000", "tax": "0,750", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 0,75.", "valor_consulta": 0.75, "api_limit_for": "credit", "homolog": false, "data": { "tipo": "voz-criacao-por-descricao-previas", "previas": [ { "previa": "Pr3v1aUmAbCdEfGhIj01", "audio_url": "https://gateway.apibrasil.io/proxy/?u=https%3A%2F%2Fvoz-criacao-por-descricao.apidocumentos.com.br%2Faudio%2F0f1e2d3c-4b5a-4978-8796-a5b4c3d2e1f0", "tipo_mime": "audio/mpeg", "tamanho_bytes": 131200, "duracao_segundos": 8.2, "expira_em": "2026-11-13T12:00:00-03:00" }, { "previa": "Pr3v1aDoisKlMnOpQr02", "audio_url": "https://gateway.apibrasil.io/proxy/?u=https%3A%2F%2Fvoz-criacao-por-descricao.apidocumentos.com.br%2Faudio%2F1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "tipo_mime": "audio/mpeg", "tamanho_bytes": 128000, "duracao_segundos": 8, "expira_em": "2026-11-13T12:00:00-03:00" }, { "previa": "Pr3v1aTresStUvWxYz03", "audio_url": "https://gateway.apibrasil.io/proxy/?u=https%3A%2F%2Fvoz-criacao-por-descricao.apidocumentos.com.br%2Faudio%2F9f8e7d6c-5b4a-4321-9876-fedcba012345", "tipo_mime": "audio/mpeg", "tamanho_bytes": 134400, "duracao_segundos": 8.4, "expira_em": "2026-11-13T12:00:00-03:00" } ], "total": 3, "caracteres": 118 } } ``` ### 2. POST /consulta/voz-criacao-por-descricao/credits ⚠️ Aviso: a chamada é cobrada (R$ 9,90) quando a voz é salva e fica disponível para a conta (HTTP 200). Campo inválido, prévia que não existe, já expirou ou não foi gerada pela sua conta, conta no limite de vozes e falha ao salvar não são cobrados. Salvar a prévia escolhida como voz da conta: Salva a prévia escolhida como voz própria da sua conta 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). Envie um POST com tipo=voz-criacao-por-descricao-salvar e: - previa (obrigatório, texto): O identificador da prévia escolhida, tirado do campo previa da resposta do tipo voz-criacao-por-descricao-previas que a sua conta pediu nas últimas 24 horas. - nome_da_voz (obrigatório, texto): Nome da voz, de 3 a 60 caracteres. É como ela aparece nas listas de vozes da sua conta. - descricao_da_voz (obrigatório, texto): A descrição da voz, de 20 a 500 caracteres. Pode ser a mesma usada para gerar as prévias quando couber (a das prévias vai até 1000). Fica gravada na voz e volta na lista de vozes da conta. Respostas de erro (nenhuma é cobrada): - HTTP 400: previa ausente ou fora do padrão (10 a 40 letras e dígitos), nome fora de 3 a 60 caracteres ou descrição fora de 20 a 500 caracteres - HTTP 404: a prévia não existe, já expirou ou não foi gerada pela sua conta nas últimas 24 horas; gere novas prévias e salve a escolhida - HTTP 422: a conta já está no limite de vozes próprias; remova uma voz para salvar outra (a resposta traz vozes_da_conta e limite_de_vozes). Repetir o pedido não adianta - HTTP 502: o serviço de voz respondeu sem a voz salva 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 serviço de voz não respondeu dentro do tempo limite Preço: R$ 9,90 por chamada. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. A prévia é provisória: salve a escolhida logo depois de gerar. Só a conta que gerou a prévia pode salvá-la, em até 24 horas. Prévia que já expirou é recusada sem cobrança, e é preciso gerar outras. A descrição e o texto de amostra são processados em servidores nos Estados Unidos. Não envie neles dado de saúde, número de cartão ou número de documento oficial, como o CPF. Não descreva a voz de uma pessoa real nem peça a imitação de alguém: este produto cria vozes novas. Para a voz de uma pessoa, com a autorização dela, use a API de Clonagem de Voz. O áudio gerado com a voz criada 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-criacao-por-descricao/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-criacao-por-descricao-salvar", "previa": "Pr3v1aUmAbCdEfGhIj01", "nome_da_voz": "Atendente virtual", "descricao_da_voz": "Voz feminina, adulta, tom acolhedor e calmo, sotaque paulistano, ritmo pausado, para atendimento.", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-criacao-por-descricao/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-criacao-por-descricao-salvar","previa":"Pr3v1aUmAbCdEfGhIj01","nome_da_voz":"Atendente virtual","descricao_da_voz":"Voz feminina, adulta, tom acolhedor e calmo, sotaque paulistano, ritmo pausado, para atendimento.","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-criacao-por-descricao-salvar", "voz": "KlMnOpQrSt9876543210", "nome_da_voz": "Atendente virtual", "vozes_da_conta": 2, "limite_de_vozes": 3 } } ``` ### 3. POST /consulta/voz-criacao-por-descricao/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 criadas por descrição quanto as clonadas. Cada voz traz o identificador (voz, o valor do campo voz nas APIs de fala), o nome, o tipo (criada ou clonada), a data de criação (criada_em) e a descriçã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-criacao-por-descricao-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. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. A prévia é provisória: salve a escolhida logo depois de gerar. Só a conta que gerou a prévia pode salvá-la, em até 24 horas. Prévia que já expirou é recusada sem cobrança, e é preciso gerar outras. A descrição e o texto de amostra são processados em servidores nos Estados Unidos. Não envie neles dado de saúde, número de cartão ou número de documento oficial, como o CPF. Não descreva a voz de uma pessoa real nem peça a imitação de alguém: este produto cria vozes novas. Para a voz de uma pessoa, com a autorização dela, use a API de Clonagem de Voz. O áudio gerado com a voz criada 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-criacao-por-descricao/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-criacao-por-descricao-vozes", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-criacao-por-descricao/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-criacao-por-descricao-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-criacao-por-descricao-vozes", "vozes": [ { "voz": "KlMnOpQrSt9876543210", "nome": "Atendente virtual", "tipo": "criada", "criada_em": "2026-11-12T10:00:00-03:00", "descricao_da_voz": "Voz feminina, adulta, tom acolhedor e calmo, sotaque paulistano, ritmo pausado, para atendimento." } ], "total": 1, "limite_de_vozes": 3 } } ``` ### 4. POST /consulta/voz-criacao-por-descricao/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 salvar 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-criacao-por-descricao-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. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. A prévia é provisória: salve a escolhida logo depois de gerar. Só a conta que gerou a prévia pode salvá-la, em até 24 horas. Prévia que já expirou é recusada sem cobrança, e é preciso gerar outras. A descrição e o texto de amostra são processados em servidores nos Estados Unidos. Não envie neles dado de saúde, número de cartão ou número de documento oficial, como o CPF. Não descreva a voz de uma pessoa real nem peça a imitação de alguém: este produto cria vozes novas. Para a voz de uma pessoa, com a autorização dela, use a API de Clonagem de Voz. O áudio gerado com a voz criada 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-criacao-por-descricao/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-criacao-por-descricao-remover", "voz": "KlMnOpQrSt9876543210", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/voz-criacao-por-descricao/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"voz-criacao-por-descricao-remover","voz":"KlMnOpQrSt9876543210","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-criacao-por-descricao-remover", "voz": "KlMnOpQrSt9876543210", "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/360ca585-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/360ca585-dec0-11f1-98bb-bc24118aba26