Como integrar a API de Texto para Fala com seu projeto

Por Equ editorial VozSinc · Atualizado 2026-11-19

Esta documentação explica como integrar nossa API de Text-to-Speech (TTS) ao seu projeto de notificações e interfaces. Aqui você encontra exemplos práticos de integração via cURL e SDK OpenAI, além de detalhes sobre parâmetros, limites de taxa e tratamento de erros para garantir uma implementação estável e eficiente.

O guia é direcionado a equipes de desenvolvimento de startups que precisam de narradores automáticos claros e de baixo custo por caractere. Você aprenderá a gerar áudio via endpoint POST, ajustar velocidades e idiomas, e gerenciar suas credenciais diretamente pelo painel da VozSinc.

Como integrar a API de Texto para Fala com seu projeto

Perguntas frequentes

Qual o endpoint principal da API?

O endpoint principal é POST https://api.cb999.info/v1/audio/speech. Você envia texto e recebe um arquivo de áudio. A estrutura do corpo da requisição é idêntica ao endpoint de fala da OpenAI, facilitando a integração imediata com seus sistemas existentes sem necessidade de adaptações complexas.

Posso usar o SDK da OpenAI?

Sim. Como o formato de requisição é o mesmo, você pode usar os SDKs oficiais da OpenAI. Basta alterar o base_url para https://api.cb999.info/v1 e utilizar sua chave de API. Isso permite uma integração rápida e familiar para desenvolvedores que já conhecem o ecossistema.

Qual o limite de caracteres por request?

Cada requisição aceita até 4096 caracteres no campo input. Para textos mais longos, você deve dividir o texto em partes dentro desse limite e juntar os arquivos de áudio resultantes. Isso garante processamento eficiente e evita erros de tamanho de payload durante a geração do áudio.

Como especifico o idioma do áudio?

Você pode usar o campo language com um código ISO opcional. Se não definido, o idioma é detectado automaticamente. Para textos em latinos que não são inglês, defina o idioma explicitamente. O sistema suporta 23 idiomas, incluindo português, espanhol, inglês, francês e alemão, entre outros.

O que é o modelo tts-1-hd?

tts-1-hd é um dos dois modelos disponíveis, junto com tts-1. Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço por caractere. A escolha entre eles não impacta o custo nem a qualidade percebida.

Posso receber áudio em formato PCM?

Sim. O campo response_format aceita os valores mp3, wav, opus, flac e pcm. Você pode escolher pcm se precisar de áudio não comprimido para processamento adicional. Todos os formatos são gerados com a mesma qualidade de voz e velocidade, variando apenas no tamanho do arquivo e compressão.

Como trato erros na resposta?

Se a síntese falhar, a cobrança é devolvida integralmente. Você deve verificar o status da resposta HTTP para identificar erros. Como não há streaming, erros ocorrem após o processamento completo ou falha do motor. Verifique seus logs e a documentação para entender códigos de erro específicos da API.

Qual a latência média de geração?

Textos longos geram áudio em tempo real aproximado, cerca de 25 caracteres por segundo. Frases curtas podem levar alguns segundos. As requisições são processadas em fila, então, sob carga, pode haver espera. Planeje sua interface considerando essa latência variável para evitar tempos de resposta excessivos para o usuário final.

Posso usar múltiplas vozes em sequência?

Sim. Você pode fazer múltiplas requisições, cada uma com um voice diferente, e concatenar os arquivos de áudio resultantes. As oito vozes disponíveis (como aria, nova, felix) podem ser alternadas livremente. Isso permite criar diálogos ou narrativas mais dinâmicas combinando timbres distintos em uma única saída de áudio.

A velocidade afeta o tamanho do arquivo?

Sim. O parâmetro speed varia de 0.25 a 4.0. Alterar a velocidade muda a duração do áudio gerado. Arquivos mais rápidos são menores em duração, enquanto os mais lentos são maiores. O custo é baseado nos caracteres de entrada, não na duração final do arquivo de áudio gerado.

Há suporte para SSML?

Não. A API não oferece suporte para SSML (Speech Synthesis Markup Language). Você não pode usar tags para controlar pausas, entonação ou pronúncia específica. A entrada é texto simples. Para controle fino, ajuste a velocidade ou divida o texto em múltiplas requisições com vozes diferentes.

Posso transmitir áudio em tempo real?

Não. Não há streaming, WebSocket ou áudio parcial. O áudio é gerado completamente e retornado no corpo da resposta. Você deve esperar a conclusão da síntese antes de receber o arquivo. Isso simplifica a implementação, mas exige que sua aplicação lide com o tempo total de geração.

Como funciona a autenticação?

A autenticação usa o cabeçalho Authorization: Bearer seguido da sua chave de API (iniciando com tts-...). Cada conta tem uma chave ativa. Você pode emitir uma nova chave a qualquer momento, invalidando a anterior instantaneamente. Mantenha sua chave segura e não a exponha no código do lado do cliente.

Onde encontro exemplos de código?

Exemplos prontos estão disponíveis na página /get-api-key/ da sua conta. Lá você encontra um exemplo de comando curl pronto para uso, além de informações sobre sua chave, saldo e uso. A estrutura é compatível com SDKs OpenAI, facilitando a adaptação para Python, Node.js, Go e outras linguagens.

Primeira solicitação

curl

curl https://api.cb999.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.cb999.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.cb999.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 API

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

Comece acessando /get-api-key/ e escolhendo login com Google ou email. Se usar Google, recebe $0,50 de crédito válido por 7 dias. A página exibe sua chave, saldo e um exemplo cURL pronto para uso.

Criação de conta via Google ou email

Criação de conta via Google ou email

A criação é imediata. Contas via email começam sem crédito de teste. Após o cadastro, o painel carrega automaticamente com suas credenciais e limite de 10 requisições por minuto.

  • Login com Google ou email + senha
  • Credenciais visíveis no painel imediatamente

Localização da chave no painel

Localização da chave no painel

A chave API aparece no topo do painel, identificada pelo prefixo "tts-". Ela é única por conta e usada no cabeçalho Authorization: Bearer.

  • Prefixo: tts-...
  • Formato: Bearer token

Geração de nova chave

Se necessário, gere uma nova chave no painel. A chave antiga é invalidada instantaneamente. Você pode emitir novas chaves quantas vezes quiser, sem custo adicional.

  • Invalidação imediata da chave anterior
  • Geração ilimitada

Primeira solicitação com cURL

Ilustração de onda sonora para: Primeira solicitação com cURL

Para começar, envie uma requisição POST para o endpoint de síntese. O serviço aceita texto bruto e retorna o arquivo de áudio diretamente, sem necessidade de configurações complexas de infraestrutura.

Endpoint POST /v1/audio/speech

Use a URL https://api.cb999.info/v1/audio/speech para enviar seus dados. A autenticação é feita via cabeçalho Authorization: Bearer SUA_CHAVE_AQUI.

JSON body com parâmetros básicos

O corpo da requisição deve conter o model ("tts-1" ou "tts-1-hd"), o input com o texto a ser falado e o voice desejado entre as 8 opções disponíveis. O idioma é opcional, mas recomendado para textos em latim que não sejam inglês.

  • model: "tts-1" ou "tts-1-hd"
  • input: string (máx. 4096 caracteres)
  • voice: nome da voz (ex: "aria")
  • response_format: mp3, wav, opus, flac ou pcm

Exemplo de código pronto para uso

Este comando cURL gera uma fala rápida em inglês usando a voz nova. Substitua sk-seu-token pela sua chave real. O arquivo de áudio será salvo localmente como output.mp3.

Integração com SDK OpenAI

Ilustração de onda sonora para: Integração com SDK OpenAI

A API de texto para fala é compatível com o SDK oficial da OpenAI, permitindo integração rápida em projetos existentes. Basta alterar o parâmetro base_url para apontar para nosso endpoint, mantendo a mesma estrutura de requisição JSON.

Essa abordagem elimina a necessidade de criar um cliente HTTP personalizado ou aprender uma nova biblioteca. Você utiliza o mesmo código de integração, apenas redirecionando a conexão para a infraestrutura da VozSinc.

Alteração do base_url

Configure o cliente SDK para usar https://api.cb999.info/v1 como base. Isso garante que todas as chamadas para o endpoint /v1/audio/speech sejam roteadas corretamente para nossa API.

A estrutura do corpo da requisição permanece idêntica ao padrão da OpenAI, facilitando a migração ou o uso conjunto de serviços.

Compatibilidade com SDK oficial

Utilize as bibliotecas oficiais da OpenAI para Python, Node.js ou Go. A compatidade é garantida pela adesão estrita ao formato de JSON esperado pelo endpoint de speech.

Isso permite que equipes já familiarizadas com o ecossistema da OpenAI integrem a VozSinc sem curva de aprendizado adicional para novos formatos de payload.

Configuração de autenticação

Inclua o cabeçalho Authorization: Bearer tts-... com sua chave única. O SDK enviará automaticamente esse cabeçalho se configurado corretamente.

Certifique-se de que a chave esteja ativa e que o saldo seja suficiente para as requisições, pois erros de autenticação ou limite excedido retornarão códigos de status HTTP apropriados.

  • Base URL: https://api.cb999.info/v1
  • Header: Authorization: Bearer <sua-chave>

Parâmetros de requisição

Ilustração de onda sonora para: Parâmetros de requisição

Os parâmetros de entrada definem como o texto será processado e qual modelo de síntese será utilizado. A escolha do modelo e a formatação da payload JSON são críticas para garantir que a resposta de áudio seja gerada corretamente, respeitando os limites de caracteres e as configurações de voz.

Este guia detalha os campos obrigatórios e opcionais do corpo da requisição, garantindo que startups integrem a API sem erros de sintaxe ou limites excedidos durante o desenvolvimento das notificações de interface.

Modelo tts-1 ou tts-1-hd

O campo model aceita apenas tts-1 ou tts-1-hd. Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço. A escolha entre eles não impacta o custo nem a qualidade percebida para casos de uso padrão de notificações, mas deve ser consistente na sua implementação.

Input de texto até 4096 caracteres

O campo input aceita strings de texto puro com limite máximo de 4096 caracteres por requisição. Espaços e pontuação contam como caracteres. Para textos mais longos, é necessário realizar o split manual e concatenar os arquivos de áudio resultantes, pois não há suporte nativo a streaming.

  • Limite rígido de 4096 caracteres por chamada POST.
  • Espaços e pontuação são contabilizados na contagem.

Voz, idioma e velocidade

Defina voice com um dos 8 presets disponíveis (ex: aria, nova, atlas). O campo language é opcional; se não fornecido, o sistema tenta adivinhar com base no script, mas para textos em latim não-ingleses, especifique o código ISO para evitar erros de pronúncia. A speed varia de 0.25 a 4.0.

Selecione vozes claras para notificações de interface. A velocidade pode ser ajustada dinamicamente para otimizar a experiência do usuário, sem alterar o custo por caractere.

  • Vozes: aria, nova, luna, sage, felix, milo, atlas, orion.
  • Idioma: código ISO opcional; padrão para latim é inglês.
  • Velocidade: faixa de 0.25 a 4.0.

Formatos de resposta suportados

Ilustração de onda sonora para: Formatos de resposta suportados

A API retorna o áudio sintetizado diretamente no corpo da resposta HTTP, permitindo que você decodifique e reproduza o arquivo imediatamente sem necessidade de armazenamento intermediário. A escolha do formato depende exclusivamente do seu caso de uso: desde a otimização de largura de banda até a preservação de fidelidade para processamento posterior.

Cada formato oferece um equilíbrio diferente entre tamanho de arquivo e qualidade de áudio. Selecione o formato mais adequado às limitações de rede dos seus usuários ou aos requisitos de qualidade dos seus sistemas de notificação automática.

MP3 para web

O formato MP3 é o padrão recomendado para a maioria das aplicações web e mobile. Ele oferece uma excelente compressão com perda mínima de qualidade perceptível, garantindo que o tempo de carregamento das notificações seja mínimo mesmo em conexões 3G ou 4G instáveis.

Use este formato para interfaces de usuário onde a latência é crítica e o armazenamento local do dispositivo é limitado.

  • Tamanho de arquivo reduzido
  • Ampla compatibilidade com players nativos
  • Ideal para streaming via HTTP

WAV para alta qualidade

O formato WAV fornece áudio sem compressão, preservando a fidelidade original da voz sintetizada. É ideal para casos onde você precisa processar o áudio posteriormente ou para gravações de alta qualidade em sistemas internos.

O tamanho do arquivo é significativamente maior que o MP3, portanto, utilize-o apenas quando a qualidade de áudio for prioritária em detrimento do uso de banda.

  • Qualidade sem perda
  • Sem compressão
  • Maior consumo de armazenamento

Opus, FLAC e PCM

Opus oferece compressão eficiente para voz, sendo excelente para aplicativos de comunicação em tempo real. FLAC é um formato sem perda de qualidade, mas com arquivo menor que WAV, útil para arquivamento. PCM é o formato bruto, não comprimido, ideal para processamento de sinal direto.

Esses formatos são úteis para desenvolvedores que necessitam de controle fino sobre o fluxo de áudio ou integração com sistemas de áudio profissionais.

Nota: O uso de formatos não padrão pode exigir codecs adicionais no cliente final.

  • Opus: alta compressão para voz
  • FLAC: qualidade sem perda
  • PCM: dados brutos
Formatos de resposta suportados

Tratamento de erros comuns

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

Identificar falhas na integração é essencial para manter a estabilidade das notificações automáticas da sua startup. A API retorna códigos de status HTTP claros para cada cenário de erro, permitindo que você ajuste o comportamento da aplicação sem interrupções bruscas.

Os erros mais frequentes estão ligados à autenticação, ao tamanho do texto ou à estrutura da requisição. Conhecer esses limites evita desperdício de créditos e garante que o áudio seja gerado corretamente.

Chave inválida ou expirada

Se a chave Authorization estiver incorreta ou revogada, o servidor retorna 401 Unauthorized. Isso ocorre quando você emite uma nova chave no painel, invalidando a anterior instantaneamente.

Verifique se o prefixo tts- está presente e se não há espaços extras na string. A autenticação é feita via cabeçalho HTTP padrão.

Limite de caracteres excedido

Cada solicitação POST aceita no máximo 4096 caracteres, incluindo espaços e pontuação. Se o texto for maior, o servidor retorna 400 Bad Request.

Para textos longos, implemente a lógica de split no seu backend, dividindo o texto em partes menores e concatenando os arquivos de áudio resultantes.

Erros de formatação JSON

O corpo da requisição deve ser um objeto JSON válido com as chaves obrigatórias: model, input e voice. Omissões ou tipos de dados incorretos geram erro 400.

Certifique-se de que o campo input seja uma string e que model seja exatamente tts-1 ou tts-1-hd.

Limites de taxa e performance

Ilustração de onda sonora para: Limites de taxa e performance

Para garantir a estabilidade do serviço, cada chave API aceita até 60 solicitações por minuto. Esse limite é aplicado por chave ativa e se aplica tanto às vozes padrão quanto às HD, sem distinção de complexidade.

60 requests por minuto

O limite de 60 requisições por minuto é rigoroso e calculado em tempo real. Se seu aplicativo dispara várias notificações simultâneas, verifique se não está excedendo essa taxa com uma única chave.

10 requests antes do primeiro top-up

Contas novas sem crédito adicionado começam com uma taxa reduzida de apenas 10 solicitações por minuto. Essa restrição visa prevenir abusos durante a fase de teste. Após o primeiro top-up via USDT, o limite padrão de 60 req/min é restaurado imediatamente.

Processamento em fila

As requisições são processadas sequencialmente. Em momentos de alta demanda, sua solicitação pode aguardar na fila antes da síntese começar. Textos longos levam mais tempo, aproximando-se do tempo real (25 caracteres por segundo), enquanto frases curtas podem levar alguns segundos adicionais devido ao enfileiramento.

Exemplos avançados de uso

Ilustração de onda sonora para: Exemplos avançados de uso

A API aceita no máximo 4.096 caracteres por requisição. Para textos longos, é necessário dividir o texto em partes e juntar os arquivos de áudio resultantes.

Essa abordagem permite integrar narrativas contínuas em fluxos de trabalho complexos sem exigir lógica adicional de frontend.

Geração de áudio longo com split

O limite de 4.096 caracteres por requisição deve ser gerenciado via lógica de cliente. O sistema retorna arquivos de áudio individuais que devem ser concatenados para reproduzir a mensagem completa, mantendo a integridade do áudio gerado.

  • Máximo de 4.096 caracteres por lote
  • Concatenação manual ou automática dos arquivos
  • Preservação da continuidade da fala

Alteração de velocidade dinamicamente

Ajuste a velocidade de fala entre 0.25 e 4.0 segundos para adaptar o tom da interface. Use valores mais altos para alertas rápidos e menores para instruções detalhadas, otimizando a experiência do usuário final.

O parâmetro speed é aplicado diretamente na geração.

  • Range: 0.25 a 4.0
  • Adaptação por tipo de notificação

Seleção de idioma explícito

  • Códigos ISO recomendados
  • Prevenção de adivinhação de idioma
  • Suporte a 23 idiomas

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Línguas como vietnamita ou indonésio não são suportadas; verifique a lista completa antes de planejar a internacionalização.

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. W3C WAI: making audio and video accessible
  3. Creative Commons Attribution 4.0
  4. LibriTTS-R corpus (OpenSLR 141)
  5. TRON developer hub: TRC-20
  6. Node.js documentation
  7. IETF RFC 7845: Ogg Opus
  8. FFmpeg documentation
  9. Tether (USDT)
  10. LibriVox public-domain audiobooks
  11. openai-node on GitHub
  12. LibriTTS-R paper (arXiv 2305.18802)

Mais neste site