Documentação completa da API de texto para voz

Por Equipe editorial VozCanta · Atualizado 2026-11-19

Esta documentação detalha a integração da API de texto para fala da VozCanta, projetada especificamente para streamers e VTubers que necessitam gerar áudio em escala. Você encontrará instruções técnicas precisas para autenticação, envio de requisições e consumo dos endpoints, utilizando o formato padrão compatible com SDKs existentes.

A página cobre desde a obtenção da chave API até o tratamento de erros e limites de taxa, além de detalhes sobre endpoints, modelos e formatos. As informações são estritamente baseadas nas especificações técnicas do produto, sem suposições, permitindo que você integre vozes consistentes e licenciadas diretamente em seus fluxos de trabalho de transmissão ao vivo ou gravação.

Documentação completa da API de texto para voz

Perguntas frequentes

O que é uma chave de API?

A chave de API é o token de autenticação necessário para acessar a API VozCanta. Ela deve ser enviada no cabeçalho Authorization como Bearer tts-... para validar suas requisições.

Como obtenho minha chave?

Você obtém sua chave acessando a página /get-api-key/ e criando uma conta via Google ou e-mail e senha. Após o registro, a página exibirá sua chave ativa, saldo, crédito de teste, caracteres restantes, histórico de uso e um exemplo de comando curl.

Posso gerar uma nova chave?

Sim, você pode emitir uma nova chave a qualquer momento diretamente pelo painel da sua conta na página /get-api-key/. A geração é imediata e permite que você gerencie o acesso à sua API conforme necessário para seus fluxos de trabalho de streaming.

A chave antiga é invalidada?

Sim, ao emitir uma nova chave, a chave anterior é invalidada instantaneamente. Isso garante que apenas a chave mais recente esteja ativa, simplificando a segurança e o controle de acesso à sua API sem necessidade de esperar expirações temporizadas.

Qual o endpoint principal?

O endpoint principal é POST https://api.zbaj.info/v1/audio/speech. Você envia texto em formato JSON e recebe um arquivo de áudio. A estrutura da requisição é idêntica à da API de fala do OpenAI, facilitando a integração com ferramentas existentes.

Posso usar o SDK do OpenAI?

Sim, você pode utilizar os SDKs oficiais do OpenAI. Basta alterar a base_url para https://api.zbaj.info/v1 e configurar a chave de API da VozCanta. Isso permite reutilizar o código existente sem necessidade de aprender uma nova biblioteca específica.

Qual o base_url necessário?

O base_url necessário é https://api.zbaj.info/v1. Configure este valor no seu cliente HTTP ou SDK para que todas as requisições, como POST para /audio/speech ou GET para /voices, sejam direcionadas corretamente para os servidores da VozCanta.

O que são os modelos tts-1?

Os modelos tts-1 e tts-1-hd são os dois modelos disponíveis, ambos utilizando o mesmo motor de síntese e preço. A escolha entre eles não altera a qualidade base ou o custo, mas permite compatibilidade com padrões de requisição conhecidos por desenvolvedores.

Qual a diferença entre tts-1 e tts-1-hd?

Não há diferença no preço ou no motor de síntese entre tts-1 e tts-1-hd. Ambos utilizam o mesmo engine e têm o mesmo custo por caractere. A distinção é apenas nominal, permitindo que você escolha o nome do modelo conforme sua preferência de código.

Quais formatos de áudio estão disponíveis?

Os formatos disponíveis são mp3, wav, opus, flac e pcm. Você pode especificar o formato desejado no campo response_format da requisição JSON. Escolha o formato que melhor se adapta ao seu fluxo de trabalho.

Qual o limite de caracteres por texto?

Cada requisição pode conter até 4096 caracteres no campo input. Para textos mais longos, você deve dividir o conteúdo em partes menores, gerar o áudio de cada parte e, em seguida, unir os arquivos de áudio resultantes para criar o arquivo final.

Quantas requisições por minuto posso fazer?

O limite padrão é de 60 requisições por minuto por chave de API. Este limite se aplica após a primeira recarga de saldo. Para contas novas sem recarga, o limite inicial é de 10 requisições por minuto até que o primeiro top-up seja realizado.

O que acontece no limite de 10 req/min?

Se você ainda não realizou o primeiro top-up, o limite é de 10 requisições por minuto. Após a primeira recarga de saldo via USDT, o limite aumenta automaticamente para 60 requisições por minuto, permitindo maior volume de geração de áudio.

Como trato erros na API?

Se a síntese falhar, o valor é devolvido integralmente na sua conta. Você não paga por requisições que não resultam em áudio. Verifique os códigos de status HTTP e a resposta JSON para identificar o erro e ajustar parâmetros como texto ou voz.

Primeira solicitação

curl

curl https://api.zbaj.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.zbaj.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.zbaj.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafeminino
novafeminino
lunafeminino
sagefeminino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Obtenha sua chave de API

Ilustração de onda sonora para: Obtenha sua chave de API

Acesse a página /get-api-key/ para criar sua conta utilizando autenticação Google ou e-mail e senha. O painel exibe sua chave API, saldo, crédito de teste, caracteres restantes, histórico de uso e um exemplo de comando curl.

Criação de conta

Criação de conta

Registre-se diretamente no site. Contas com login Google recebem $0,50 de crédito de teste válido por 7 dias. Contas criadas com e-mail e senha iniciam sem crédito.

Gerenciamento de chaves

Gerenciamento de chaves

Cada conta possui uma chave ativa visível no painel. Você pode gerar uma nova chave a qualquer momento para substituir a anterior.

  • Autenticação via cabeçalho Authorization: Bearer
  • Formato: tts-...

Chave única ativa

Ao emitir uma nova chave, a anterior deixa de funcionar imediatamente. Utilize apenas uma chave por conta para garantir o controle correto dos limites e do saldo.

Primeira solicitação (curl)

Ilustração de onda sonora para: Primeira solicitação (curl)

Utilize a interface de linha de comando para validar a integração da API VozCanta. Este método direto permite testar a geração de áudio sem dependência de bibliotecas externas, configurando a estrutura JSON necessária para a síntese.

A solicitação deve incluir o modelo, o texto de entrada e a voz desejada. O endpoint aceita requisições POST padrão, facilitando a automação em scripts bash ou ferramentas de teste como Postman.

Comando curl básico

Execute a chamada via terminal substituindo <SUA_CHAVE> pelo token de autenticação.

  • Autenticação: Authorization: Bearer tts-...
  • Endpoint: https://api.zbaj.info/v1/audio/speech
  • Método: POST

Parâmetros JSON

O corpo da requisição requer o campo input com o texto a ser convertido (máximo 4096 caracteres). Defina model como tts-1 ou tts-1-hd e selecione uma das 8 vozes disponíveis via campo voice.

  • model: "tts-1" ou "tts-1-hd"
  • input: texto string (até 4096 chars)
  • voice: identificador da voz (ex: "aria")
  • response_format: "mp3", "wav", "opus" ou "flac"

Resposta de áudio

O sucesso retorna o código 200 com o arquivo de áudio binário diretamente no corpo da resposta. Para formatos como MP3, o arquivo pode ser salvo diretamente no disco ou reproduzido.

SDK OpenAI

Ilustração de onda sonora para: SDK OpenAI

O SDK oficial da OpenAI pode ser reutilizado diretamente na API VozCanta, exigindo apenas a alteração do ponto de conexão. Isso permite que desenvolvedores integrem a geração de áudio em fluxos de trabalho existentes sem escrever código HTTP personalizado do zero.

Configure o parâmetro base_url para apontar para o domínio da API VozCanta e utilize sua chave de autenticação válida. A estrutura do JSON permanece idêntica ao padrão OpenAI, garantindo compatibilidade imediata com bibliotecas oficiais.

Configuração do base_url

Defina a variável de ambiente ou parâmetro de conexão para https://api.zbaj.info/v1. Esta URL substitui o endpoint padrão da OpenAI, redirecionando todas as solicitações para a infraestrutura da VozCanta.

Uso do SDK oficial

Utilize as bibliotecas oficiais (Python, Node.js, etc.) importando o cliente padrão. Passe sua chave API no cabeçalho Authorization e invoque o método de speech conforme o modelo tts-1 ou tts-1-hd.

Compatibilidade

A forma da requisição é idêntica à da API de fala do OpenAI, permitindo o uso dos SDKs oficiais da OpenAI com a alteração do base_url. Não há necessidade de adaptações de campo ou lógica de negócio, apenas a troca do endpoint de conexão.

Endpoints disponíveis

Ilustração de onda sonora para: Endpoints disponíveis

A API oferece três endpoints principais para integração. O endpoint principal processa a síntese de voz, enquanto os outros fornecem metadados sobre vozes e modelos disponíveis.

Todos os endpoints requerem autenticação via cabeçalho Bearer com a chave de API do usuário.

POST /v1/audio/speech

Endpoint principal para síntese. Recebe texto até 4096 caracteres e retorna áudio.

Suporta formatos mp3, wav, opus, flac e pcm. Parâmetros incluem model, voice, speed e input.

  • Método: POST
  • Formato: JSON
  • Retorno: Arquivo de áudio binário

GET /v1/voices

Retorna lista de 8 vozes disponíveis, idiomas suportados e formatos.

Permite verificar disponibilidade de vozes antes da síntese.

  • Retorna: lista de vozes
  • Inclui: idiomas e formatos

GET /v1/models

Retorna modelos tts-1 e tts-1-hd disponíveis.

Útil para verificar compatibilidade de modelos no ambiente.

  • Retorna: lista de modelos
  • Inclui: IDs de modelo

Modelos de voz

Ilustração de onda sonora para: Modelos de voz

A API oferece dois modelos de geração de voz acessíveis através do campo model nas requisições. A escolha entre as opções não altera a qualidade base da síntese, mas define o formato de saída padrão e a experiência de latência percebida durante o processamento.

tts-1 padrão

Modelo padrão. Ideal para fluxos de trabalho gerais. Utilize este modelo para a maioria das integrações onde o equilíbrio entre velocidade e custo é prioritário. O formato de resposta padrão é MP3, garantindo compatibilidade universal com players de stream e DAWs.

tts-1 hd alta qualidade

Modelo de alta definição. Selecione tts-1-hd quando precisar de máxima fidelidade para gravações finais ou vídeos editados. O formato padrão de resposta é WAV, preservando a integridade do áudio sem compressão com perdas, ideal para pós-produção profissional.

Mesmo motor e preço

Ambos os modelos utilizam o mesmo motor de síntese subjacente. A diferença reside exclusivamente na codificação do arquivo de áudio retornado. Não há distinção de preço entre tts-1 e tts-1-hd; o custo é fixo em $10 por 1 milhão de caracteres processados, independentemente da opção escolhida.

  • Mesma engine de processamento
  • Mesmo preço por caractere
  • Diferença apenas na codificação de saída
Modelos de voz

Formatos de saída

Ilustração de onda sonora para: Formatos de saída

A API VozCanta oferece múltiplas opções de formato de áudio para atender às exigências técnicas de streams e gravações. O campo response_format na solicitação POST define a codificação do arquivo retornado, permitindo flexibilidade entre compatibilidade universal e qualidade de produção.

MP3 compatível

O formato MP3 é a opção padrão, otimizado para transmissão e armazenamento eficiente. Ideal para integração direta com plataformas de streaming e players web, garantindo compatibilidade ampla sem necessidade de conversões adicionais.

  • Tamanho de arquivo reduzido
  • Ampla compatibilidade com players

WAV sem perda

O WAV é um formato de áudio padrão amplamente suportado por software de edição e DAWs. Este formato é adequado para workflows de pós-produção onde a integridade do arquivo é prioritária sem overhead de codificação complexo.

  • Formato padrão de indústria
  • Baixa latência de processamento

OPUS e FLAC

O OPUS oferece compressão eficiente para streaming de baixa latência, enquanto o FLAC garante áudio sem perda de bits. Ambos são válidos para response_format, atendendo a necessidades específicas de qualidade ou eficiência de banda.

  • OPUS: alta eficiência
  • FLAC: sem perda de bits

Limites e velocidade

Ilustração de onda sonora para: Limites e velocidade

O limite padrão da API é de 60 requisições por minuto por chave. Isso permite o processamento de múltiplas requisições, adequado para fluxos de trabalho de streaming.

60 requisições por minuto

Cada chave de API permite até 60 requisições por minuto. Esse limite é suficiente para a maioria dos cenários de uso, incluindo a geração de frases curtas e parágrafos longos divididos em partes de 4096 caracteres.

Limite inicial

Antes da primeira recarga de saldo, o limite é reduzido para 10 requisições por minuto. Isso garante o uso consistente do serviço durante o período de teste gratuito, evitando sobrecarga na infraestrutura antes da confirmação do pagamento.

Aumento após recarga

Após a transferência de USDT na rede TRON (TRC-20), o limite volta para 60 requisições por minuto automaticamente. O saldo é creditado em minutos. A velocidade de geração é de aproximadamente 25 caracteres de texto por segundo de áudio gerado.

Tratamento de erros

Ilustração de onda sonora para: Tratamento de erros

A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha da síntese. O status 200 indica que o áudio foi gerado com sucesso. Valores diferentes de 200 indicam erros de requisição, autenticação ou limites excedidos, permitindo que o cliente ajuste a lógica de retry conforme necessário.

Códigos de status

O endpoint principal utiliza HTTP 200 para respostas bem-sucedidas. Outros códigos, como 400 (Bad Request) ou 401 (Unauthorized), indicam problemas específicos na entrada ou nas credenciais. Consulte a seção de endpoints para detalhes técnicos sobre cada código de erro retornado pelo servidor.

Solicitações falhas

Se a síntese falhar durante o processamento, o arquivo de áudio não é retornado. A falha não consome crédito da sua conta. O status da requisição refletirá o erro ocorrido, permitindo que você identifique se o problema foi técnico ou de entrada de dados.

Reembolso automático

O crédito é devolvido integralmente caso a síntese não seja concluída com sucesso. Não há necessidade de solicitar reembolso manualmente. O valor volta para o seu saldo automaticamente, mantendo a precisão na contagem de caracteres consumidos.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Isso garante que a base de áudio utilizada para a síntese possua licenças claras e verificáveis para uso comercial.

Avatar da voz aria
ariafeminino
Avatar da voz nova
novafeminino
Avatar da voz luna
lunafeminino
Avatar da voz sage
sagefeminino
Avatar da voz felix
felixmasculino
Avatar da voz milo
milomasculino
Avatar da voz atlas
atlasmasculino
Avatar da voz orion
orionmasculino

23 idiomas

Qualquer voz fala qualquer um desses idiomas.

Fontes e leituras adicionais

  1. Wikipedia
  2. IETF RFC 7845: Ogg Opus
  3. Creative Commons Attribution 4.0
  4. curl documentation
  5. TRON developer hub: TRC-20
  6. FFmpeg documentation
  7. Tether (USDT)
  8. MDN: Web Speech API
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. OpenAI API reference: create speech
  11. Node.js documentation
  12. Python documentation

Mais neste site