Perguntas frequentes
Qual o formato de corpo da requisição?
O corpo da requisição deve ser enviado como JSON. Os campos aceitos são model, input, voice, response_format, speed e language. A estrutura é idêntica ao endpoint de fala da OpenAI, facilitando a integração imediata com seus sistemas existentes.
Posso usar o SDK oficial da OpenAI?
Sim. Como o formato de requisição é o mesmo, você pode usar os SDKs da OpenAI. Basta alterar o base_url para https://api.0657.info/v1 e utilizar sua chave de API própria. A: Sim. Como o formato de requisição é o mesmo, você pode usar os SDKs da OpenAI.
Qual o limite máximo de caracteres por solicitação?
Cada solicitação aceita até 4096 caracteres. Se o texto for maior, você deve dividi-lo em partes menores e juntar os arquivos de áudio resultantes. Essa abordagem garante que cada chamada seja processada eficientemente, mantendo a qualidade do áudio e respeitando os limites técnicos da API.
A velocidade afeta o custo da API?
Não. O custo é calculado exclusivamente com base no número de caracteres do texto de entrada, independentemente da velocidade ajustada. A velocidade (entre 0.25 e 4.0) altera apenas a duração do áudio gerado, mas não impacta a contagem de caracteres nem o valor cobrado na sua conta.
O que é o modelo tts-1-hd?
O modelo tts-1-hd é uma das duas opções de motor de síntese disponíveis, oferecendo alta qualidade de áudio. Ele possui o mesmo preço do modelo padrão tts-1, permitindo que você escolha a qualidade desejada sem variação de custo. Ambos utilizam as mesmas vozes e configurações disponíveis.
Posso enviar texto em vários idiomas na mesma solicitação?
Sim, você pode enviar texto em vários idiomas. A API detecta automaticamente o idioma com base no script, mas você pode forçar um idioma específico usando o campo language. Se não for definido, o texto em latim é assumido como inglês. O contexto muda naturalmente entre idiomas.
Como detectar erros de formatação JSON?
A API retorna códigos de status HTTP padrão para erros de sintaxe ou campos ausentes. Verifique o código de status na resposta (como 400 para erro de entrada). O corpo da resposta conterá uma mensagem detalhando o campo com problema, permitindo correção imediata na estrutura JSON enviada.
A API retorna metadados do áudio?
A resposta contém o arquivo de áudio diretamente, sem metadados extensos sobre o conteúdo gerado. Os metadados de uso, como tempo, caracteres e status, são mantidos para faturamento e visíveis no painel da conta. Não há informação embutida no arquivo de áudio sobre a voz ou modelo utilizado.
Qual o tempo médio de resposta?
O tempo varia conforme o tamanho do texto e a carga do sistema. Textos longos são gerados em tempo real aproximado, cerca de 25 caracteres por segundo. Frases curtas levam alguns segundos. Em momentos de alta demanda, as requisições podem aguardar na fila antes do processamento.
Posso usar HTTPS sem certificado customizado?
Sim. A API utiliza HTTPS padrão. Não é necessário configurar certificados customizados ou validar CNs específicos além do domínio da API. A conexão segura é estabelecida automaticamente pelas bibliotecas HTTP padrão.
A chave API é sensível?
Sim. A chave deve ser mantida em sigilo, pois concede acesso à sua conta e saldo. Cada conta possui uma chave ativa por vez. Se você emitir uma nova chave, a anterior é invalidada imediatamente. Proteja sua chave como faria com uma senha de acesso principal.
Há limite de tamanho do arquivo de áudio retornado?
Não há um limite rígido de tamanho de arquivo especificado, mas o tamanho depende diretamente da duração do texto e da velocidade. Como cada requisição é limitada a 4096 caracteres, o arquivo resultante terá tamanho proporcional a essa duração máxima, gerenciável pela divisão de textos longos.
Posso usar o mesmo endpoint para diferentes vozes?
Sim. O endpoint POST /v1/audio/speech é único para todas as vozes. Você seleciona a voz desejada (como aria, nova, ou atlas) passando o nome dela no campo voice da requisição JSON. Isso permite alternar entre vozes femininas e masculinas sem alterar a URL ou a estrutura da chamada.
O que acontece se exceder os 60 requests por minuto?
Se exceder 60 solicitações por minuto, as requisições adicionais receberão um erro de limite de taxa. Você deve aguardar até que o contador de tempo recomece ou reduzir a frequência de chamadas. Esse limite é aplicado por chave de API e garante a estabilidade do serviço para todos os usuários.
Primeira solicitação
curl
curl https://api.0657.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.0657.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.0657.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 | |
|---|---|
aria | feminino |
nova | feminino |
luna | feminino |
sage | feminino |
felix | masculino |
milo | masculino |
atlas | masculino |
orion | masculino |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Autenticação e chave API
A autenticação na API VozSintonia utiliza o padrão Bearer Token. A chave API, iniciada por "tts-", deve ser enviada no cabeçalho Authorization de cada requisição HTTP. Ela é exclusiva para a conta criada no site e garante o acesso aos endpoints de síntese e configuração.
Formato da chave Bearer
Inclua o cabeçalho Authorization: Bearer tts-... em todas as chamadas. O formato segue o padrão OAuth 2.0, compatível com bibliotecas HTTP modernas e SDKs de terceiros.
Emissão de nova chave
Acesse o painel /get-api-key/ para visualizar sua chave ativa. Você pode gerar uma nova chave a qualquer momento diretamente na interface da conta.
Revogação automática
A geração de uma nova chave invalida imediatamente a anterior. Não há período de carência; a chave antiga deixa de funcionar no exato momento da criação da nova, garantindo segurança imediata sem necessidade de confirmação manual.
Endpoint principal de síntese
A síntese de voz é realizada enviando texto para o endpoint POST /v1/audio/speech. O serviço retorna o arquivo de áudio pronto para uso, sem necessidade de streaming ou conexões WebSocket. Esta abordagem simplifica a integração em pipelines de atendimento automatizado.
O formato de corpo JSON segue o padrão usado pelo endpoint de speech da OpenAI, permitindo reutilizar bibliotecas existentes. Basta ajustar o base_url para https://api.0657.info/v1. Isso facilita a migração e a manutenção de código em equipes de desenvolvimento.
A API processa requisições sequencialmente, garantindo que cada solicitação seja executada individualmente. Isso é ideal para chatbots que não exigem latência de tempo real estrita, focando na precisão da geração de áudio.
Método POST /v1/audio/speech
Utilize o método POST para enviar texto e receber áudio. O endpoint aceita requisições JSON padrão, compatível com a maioria das linguagens de programação.
A resposta contém o arquivo de áudio no formato solicitado, pronto para ser reproduzido ou armazenado temporariamente em seus servidores.
- URL base:
https://api.0657.info/v1 - Método: POST
- Formato de resposta: arquivo de áudio binário
Corpo JSON padrão
O corpo da requisição deve incluir o texto a ser sintetizado e a voz desejada. O formato é idêntico ao usado na API de speech da OpenAI.
Isso permite o uso do SDK da OpenAI, alterando apenas a URL base. Campos como model e voice são especificados no corpo JSON.
A API não suporta SSML ou marcações de emoção, mantendo a estrutura simples e previsível para automações.
Campos obrigatórios e opcionais
Os campos model, input e voice são essenciais para a síntese. O model define a qualidade (tts-1 ou tts-1-hd), o input contém o texto e o voice seleciona o timbre.
Parâmetros como response_format, speed e language são opcionais. A linguagem é inferida automaticamente, mas deve ser definida para textos em latim não ingleses.
Cada requisição processa até 4096 caracteres. Textos maiores devem ser divididos manualmente antes do envio.
Parâmetros de entrada
Os parámetros de entrada definem como o texto será convertido em áudio. A configuração básica inclui o modelo, o texto de entrada, a voz, a velocidade e o idioma.
Esta seção detalha os campos obrigatórios e opcionais para garantir a síntese correta nas suas aplicações de assistente virtual.
Modelo tts-1 e 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 por caractere. A escolha entre eles é baseada na qualidade de áudio desejada, sem diferença de custo ou performance de latência.
Input texto até 4096 caracteres
- Limite: 4096 caracteres por chamada.
- Custo: $0,01 por 1.000 caracteres (espaços incluídos).
Voice, speed e language
O campo voice recebe uma das 8 presets disponíveis (ex: aria, nova, felix). O campo speed ajusta a velocidade entre 0.25 e 4.0. O language é opcional; se não fornecido, o idioma é detectado pelo script, com padrão inglês para texto em latim.
- Voizes: 8 presets fixos (ex: aria, milo).
- Velocidade: 0.25 a 4.0.
- Idioma: detectado automaticamente ou definido via ISO code.
Formatos de áudio suportados
A API aceita MP3, WAV, OPUS, FLAC e PCM para atender diferentes necessidades de infraestrutura. A escolha do formato impacta diretamente a latência e o tamanho do arquivo, permitindo equilibrar velocidade de entrega e qualidade de áudio conforme o requisito do sistema.
Para assistentes virtuais, formatos leves como OPUS reduzem o tempo de resposta, enquanto WAV ou FLAC são ideais para gravações de alta fidelidade. O PCM é útil para integrações que exigem áudio bruto não comprimido.
MP3, WAV, OPUS, FLAC, PCM
Todos os formatos listados são suportados nativamente no campo response_format da requisição. A API gera o arquivo correspondente imediatamente após a síntese bem-sucedida.
Escolha baseada em latência
Se o seu chatbot requer resposta imediata, utilize OPUS ou MP3. Eles oferecem melhor relação tamanho/qualidade para transferência via HTTP padrão, minimizando o tempo de espera do usuário final.
Qualidade vs. tamanho
Escolha WAV ou FLAC se precisar de áudio sem perda de compressão para análise posterior ou gravação em banco de dados. O PCM fornece dados brutos, ideal para processamento de sinal contínuo sem decodificação intermediária.
Limites de taxa e fila
Os limites de taxa garantem estabilidade para equipes de desenvolvimento que integram voz a chatbots. O sistema processa requisições em fila sequencial, priorizando a integridade do áudio gerado.
Compreender esses limites ajuda a ajustar a arquitetura de chamadas, evitando throttling desnecessário durante picos de uso em assistentes virtuais.
60 requisições por minuto
Cada chave API permite até 60 requisições por minuto. Esse limite é suficiente para a maioria dos fluxos de atendimento padrão e garante que o serviço permaneça responsivo mesmo sob carga moderada.
10 requisições iniciais
Contas recém-criadas começam com uma cota reduzida de 10 requisições por minuto. Isso permite testar a integração sem saturar os recursos imediatamente. O limite é elevado automaticamente após o primeiro top-up.
Processamento sequencial
As requisições são processadas uma após a outra. Para textos longos, o áudio é gerado em partes e unido posteriormente. Em momentos de alta demanda, uma requisição pode aguardar na fila antes do início da síntese.

Exemplo com curl
O comando abaixo demonstra a chamada direta à API para gerar áudio de um assistente virtual. Substitua a chave de autenticação e o texto de exemplo antes de executar.
A resposta retorna o arquivo de áudio binário diretamente no corpo da resposta, permitindo o processamento imediato sem necessidade de download adicional.
Comando completo
Execute a solicitação POST para o endpoint de síntese. O corpo JSON deve conter o modelo, o texto a ser falado e o identificador da voz desejada.
Certifique-se de que o texto não exceda 4096 caracteres e que a chave Bearer esteja correta no cabeçalho de autorização.
- Endpoint: POST https://api.0657.info/v1/audio/speech
- Formato: application/json
- Autenticação: Bearer tts-sua-chave-aqui
Resposta esperada
O servidor retornará o arquivo de áudio no formato solicitado (mp3, wav, opus, flac ou pcm). O conteúdo da resposta é binário e pronto para ser reproduzido ou armazenado.
A latência depende do comprimento do texto e da fila de processamento, sendo geralmente próxima do tempo real para textos longos.
Tratamento de erro
Se a síntese falhar, o crédito será devolvido integralmente. Verifique os códigos de status HTTP para identificar problemas de autenticação ou limites de taxa excedidos.
Para erros de corpo da requisição, a resposta incluirá uma mensagem clara indicando o campo inválido ou a restrição violada.
Integração com OpenAI SDK
A API de síntese de voz é compatível com os SDKs da OpenAI. Para utilizá-los, basta alterar a propriedade base_url para https://api.0657.info/v1 e configurar a chave API no cabeçalho de autenticação.
Essa configuração permite que você utilize as mesmas bibliotecas que já conhece, mantendo a estrutura de código existente sem necessidade de adaptações complexas.
Configuração do base_url
Defina base_url como https://api.0657.info/v1. Utilize a mesma chave tts-... gerada em sua conta.
O SDK enviará automaticamente o cabeçalho Authorization: Bearer para cada requisição.
- Base URL: https://api.0657.info/v1
- Autenticação: Bearer <sua-chave-api>
Uso do mesmo formato de corpo
O corpo JSON segue o padrão da endpoint de fala da OpenAI. Campos como model, input, voice e response_format funcionam da mesma forma.
A velocidade (speed) aceita valores de 0.25 a 4.0, permitindo ajustes precisos para seus fluxos de chatbot.
Compatibilidade total
As bibliotecas da OpenAI funcionam diretamente com nossa API. Não é necessário instalar pacotes adicionais ou criar wrappers customizados.
A estrutura de resposta também é idêntica, facilitando o tratamento do arquivo de áudio gerado em suas aplicações.
- SDKs da OpenAI compatíveis
- Estrutura de resposta idêntica
Tratamento de erros
A API retorna códigos HTTP padrão para indicar o status de cada requisição. Código 200 indica sucesso, enquanto 400 sinaliza parâmetros inválidos e 429 indica limite de taxa excedido. Cada resposta contém detalhes específicos para facilitar o diagnóstico rápido.
Códigos de status HTTP
Use os códigos padrão HTTP para controle de fluxo. 200 OK para sucesso, 400 Bad Request para erros de validação, 401 Unauthorized para chave inválida e 429 Too Many Requests quando o limite de 60 rpm for atingido.
- 200: Sucesso, áudio retornado.
- 400: Parâmetros inválidos (ex: texto > 4096 chars).
- 401: Chave de API ausente ou inválida.
- 429: Limite de taxa excedido (rate limit).
Mensagens de erro claras
Cada erro de validação inclui uma mensagem descritiva no corpo JSON da resposta. Isso permite que você identifique exatamente qual campo falhou (modelo, voz ou formato) sem precisar adivinhar.
Retorno de crédito em falhas
Se a síntese falhar, o crédito correspondente é devolvido integralmente à sua conta. Não há cobrança por tentativas que resultem em erro, garantindo que você pague apenas por áudio gerado com sucesso.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
