Perguntas frequentes
Qual é o endpoint principal da API?
O endpoint principal é POST https://api.552x.info/v1/audio/speech. Você envia o texto e recebe o arquivo de áudio. A estrutura do corpo da requisição JSON é idêntica à da API de fala da OpenAI, facilitando a integração com seus sistemas existentes de processamento de áudio.
Como faço a autenticação na API?
Utilize o cabeçalho Authorization: Bearer tts-... com sua chave ativa. Cada conta possui uma única chave válida. Se você emitir uma nova chave, a anterior é invalidada imediatamente. Consulte sua chave e saldo na página /get-api-key/ após o cadastro.
Posso usar o SDK da OpenAI?
Sim. Como o formato da requisição é o mesmo, você pode usar os SDKs da OpenAI. Basta alterar o base_url para https://api.552x.info/v1 e utilizar sua chave de API específica. Isso permite uma integração rápida sem necessidade de bibliotecas adicionais.
Qual a diferença entre tts-1 e tts-1-hd?
Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço. A escolha entre 'tts-1' e 'tts-1-hd' não altera o custo nem a qualidade percebida do áudio gerado. Ambos aceitam os mesmos parâmetros de voz, idioma e formato de resposta.
Quais formatos de áudio são suportados?
A API suporta os formatos mp3, wav, opus, flac e pcm. Você deve especificar o formato desejado no campo response_format da requisição. A escolha do formato depende das necessidades de compatibilidade do seu player ou sistema de armazenamento de áudio.
Qual o limite de caracteres por solicitação?
Cada solicitação aceita até 4096 caracteres. Textos longos devem ser divididos em partes menores e os arquivos de áudio resultantes devem ser unidos. Caracteres de espaço e pontuação contam para o limite total de caracteres da entrada de texto.
Como ajustar a velocidade da voz?
Use o parâmetro speed na requisição, aceitando valores entre 0.25 e 4.0. O valor padrão é 1.0. Ajustar a velocidade permite adaptar o áudio gerado ao ritmo desejado para notícias ou boletins, mantendo a clareza da fala sintética.
O que acontece ao atingir o limite de requisições?
O limite é de 60 requisições por minuto por chave (10 antes do primeiro recarga). As requisições são processadas em fila, então você pode esperar um pouco sob carga. Pedidos falhados não consomem crédito e são processados sem custo adicional.
Como obter a lista de vozes disponíveis?
Faça uma requisição GET para o endpoint /v1/voices. Esta rota retorna informações sobre vozes, idiomas, formatos suportados e preços. Use essa informação para selecionar a voz ideal, como 'aria' ou 'atlas', antes de gerar o áudio.
A API retorna áudio em streaming?
Não. A API retorna o arquivo de áudio completo na resposta. Não há suporte para streaming, WebSocket ou áudio parcial em tempo real. Você deve aguardar o processamento completo da solicitação para receber o arquivo final.
Existe suporte para SSML?
Não. A API não oferece suporte para marcação SSML. Você não pode usar tags para controlar pausas, entonação ou pronúncia específica. O texto é processado diretamente, e a entonação é definida apenas pela escolha da voz e velocidade.
Como funcionam os códigos de erro?
O código de status HTTP indica o sucesso ou falha. Solicitações com falha na síntese são gratuitas e o crédito é devolvido integralmente. Verifique a documentação para detalhes sobre códigos específicos, mas a falha sempre resulta em reembolso automático.
Posso especificar o idioma manualmente?
Sim, use o campo language com um código ISO. Se não especificado, o idioma é adivinhado pelo script (texto latino assume inglês). Para textos em latim não ingleses, defina o idioma manualmente para garantir a pronúncia correta pela voz selecionada.
Qual o formato de resposta da API?
A resposta contém o arquivo de áudio binário no formato solicitado. O corpo da resposta é o áudio em si, pronto para ser salvo ou reproduzido. Não há metadados JSON anexados ao arquivo de áudio na resposta padrão.
Primeira solicitação
curl
curl https://api.552x.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.552x.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.552x.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 é feita via token Bearer. Para começar, acesse /get-api-key/ e registre-se com Google ou email. Uma chave única (tts-...) é emitida imediatamente para suas requisições.
Cada conta mantém apenas uma chave ativa. Se você gerar uma nova, a anterior é invalidada instantaneamente, garantindo que apenas um token válido esteja em uso no momento.
Obtenção da chave de acesso
Registre-se em /get-api-key/. O sistema emite sua chave API automaticamente após o login com Google ou criação de conta por email. Use este token em todas as chamadas à API.
- Login via Google ou email/senha
- Chave única ativa por conta
- Acesso imediato sem aprovação manual
Formato do cabeçalho Bearer
Inclua o cabeçalho Authorization: Bearer <sua-chave> em cada requisição HTTP. A chave começa com tts- e deve ser mantida em sigilo nos seus ambientes de produção.
Revoque de chave anterior
Gerar uma nova chave revoga a anterior imediatamente. Não há período de grace period; a chave antiga deixa de funcionar no exato momento da nova emissão.
Endpoint principal de síntese
Envie texto para síntese via POST para /v1/audio/speech. A API processa strings de até 4096 caracteres e retorna o arquivo de áudio diretamente na resposta. Para textos longos, divida a entrada em partes menores e junte os arquivos gerados.
Método POST para /v1/audio/speech
Use o método POST no endpoint /v1/audio/speech para iniciar a síntese. O corpo da requisição deve ser JSON. A resposta contém o arquivo de áudio binário ou um erro JSON.
Corpo da requisição JSON
O corpo deve conter os campos obrigatórios e opcionais descritos abaixo. Certifique-se de que o texto não exceda 4096 caracteres por requisição.
- "model": "tts-1" ou "tts-1-hd"
- "input": texto a ser convertido (string)
- "voice": ID da voz (ex: "aria")
- "response_format": "mp3", "wav", "opus", "flac" ou "pcm"
- "speed": número entre 0.25 e 4.0
- "language": código ISO (opcional)
Parâmetros obrigatórios e opcionais
Os parâmetros obrigatórios são model, input, voice e response_format. O parâmetro language é opcional; se não fornecido, o sistema tenta adivinhar o idioma pelo script, assumindo inglês para texto em latim.
Modelos de voz disponíveis
O endpoint de síntese aceita dois valores para o campo model: tts-1 e tts-1-hd. Ambos utilizam exatamente o mesmo motor de síntese de voz, garantindo consistência acústica entre as opções.
Essa estrutura simplifica a integração para equipes de produto de mídia, permitindo que você altere a qualidade percebida sem modificar a lógica de chamada da API ou o processamento do áudio gerado.
Modelo tts-1 padrão
O modelo tts-1 é a configuração base para geração de áudio via API. Ele processa textos em até 4096 caracteres por solicitação, entregando o resultado em formatos como MP3, WAV, OPUS, FLAC ou PCM.
Modelo tts-1-hd alta qualidade
O modelo tts-1-hd oferece a mesma engine do padrão, mantendo a fidelidade das vozes licenciadas de audiolivros. Ideal para notícias e boletins onde a clareza vocal é prioritária, sem complexidade adicional de integração.
Mesmo motor e preço
Como ambos compartilham o mesmo motor, o custo é idêntico: $0,01 por mil caracteres. A escolha entre tts-1 e tts-1-hd não impacta a fatura nem a latência de processamento, focando apenas na preferência técnica de formato.
Formatação e velocidade do áudio
A API aceita cinco formatos de saída: MP3, WAV, OPUS, FLAC e PCM. A escolha deve considerar a eficiência de armazenamento versus a qualidade de reprodução nativa do player do cliente. O formato padrão é MP3, garantindo compatibilidade universal em navegadores e dispositivos móveis sem necessidade de transcodificação adicional.
Suporte a MP3, WAV, OPUS, FLAC, PCM
O parâmetro response_format define o container do áudio retornado. MP3 é recomendado para web geral; WAV e FLAC oferecem qualidade lossless; OPUS é eficiente para streaming; PCM é puro, sem compressão.
- MP3: padrão, leve, universal.
- WAV/FLAC: alta fidelidade.
- OPUS: compactação eficiente.
- PCM: áudio cru.
Controle de velocidade de 0.25 a 4.0
O parâmetro speed ajusta a taxa de fala entre 0.25 e 4.0. O valor padrão é 1.0. Velocidades maiores reduzem o tempo de geração, útil para boletins rápidos, enquanto valores menores aumentam a clareza para auditiva ou traduções.
Formato padrão de resposta
O corpo da resposta contém os bytes binários do arquivo de áudio diretamente. Não há envelope JSON para o áudio, facilitando o salvamento direto em disco ou envio via HTTP sem parsing adicional.
Exemplo de requisição com cURL
Para testar rapidamente a API de síntese de voz, utilize o comando cURL abaixo. Ele envia um texto simples para o endpoint principal e recebe o arquivo de áudio diretamente no terminal.
Lembre-se de substituir SUA_CHAVE_AQUI pela chave real obtida na seção de autenticação. O comando usa o formato JSON padrão, garantindo compatibilidade imediata com seus scripts existentes.
Comando pronto para uso
Execute este comando no seu terminal para gerar um arquivo MP3 a partir do texto fornecido. A resposta será o áudio bruto.
O modelo tts-1 é utilizado por padrão, oferecendo boa qualidade com baixa latência para fluxos de trabalho de notícias.
- Substitua
SUA_CHAVE_AQUIpela sua chave Bearer. - O texto de exemplo é limitado a 4096 caracteres.
- O formato de resposta é binário por padrão.
Substituição da chave de API
Insira sua chave única no cabeçalho Authorization. Cada conta possui apenas uma chave ativa por vez, renovável instantaneamente.
Se você gerar uma nova chave, a anterior deixa de funcionar imediatamente, garantindo segurança sem atrasos.
Verificação de resposta binária
A resposta não é JSON, mas sim o arquivo de áudio direto. Use a flag -o para salvar o arquivo localmente.
Se a síntese falhar, você receberá um código de erro HTTP e não será cobrado pelo uso de caracteres.

Integração com SDK OpenAI
A API de síntese de voz segue o formato de solicitação do endpoint de fala da OpenAI, permitindo que equipes de produto de mídia aproveitem bibliotecas existentes para integração rápida. Basta alterar o base_url para https://api.552x.info/v1 e utilizar a chave de API do VozNoticia no cabeçalho de autorização.
Essa compatibilidade facilita a transição de provedores de TTS sem a necessidade de reescrever toda a lógica de chamada de áudio. O código Python ou JavaScript permanece estruturalmente idêntico, garantindo que os fluxos de geração de notícias e boletins sejam mantidos com mínimas alterações de configuração.
Alteração da base_url
Para integrar o VozNoticia, configure o cliente da biblioteca OpenAI apontando para o domínio api.552x.info. A estrutura de payload é idêntica, exigindo apenas a atualização da URL base e da chave de autenticação Bearer.
Reutilização de código existente
Scripts que já consomem o endpoint /v1/audio/speech funcionam imediatamente. A única mudança necessária é substituir a chave da API e o endereço base. Isso reduz o tempo de desenvolvimento para equipes de produto, permitindo focar na lógica de negócio e não na infraestrutura de áudio.
Compatibilidade com bibliotecas oficiais
Os SDKs oficiais da OpenAI (para Python, Node.js, etc.) são diretamente compatíveis. Você pode utilizar os mesmos objetos de configuração e métodos de envio, garantindo que a integração seja estável e previsível, sem dependências de pacotes proprietários adicionais.
Limites e tratamento de erros
O limite padrão é de 60 requisições por minuto por chave. Antes do primeiro recarga, esse limite cai para 10 por minuto. Quando há fila de processamento, o tempo de resposta pode aumentar devido ao processamento sequencial.
Limite de 60 requisições por minuto
As requisições são processadas em fila. Para textos longos, a geração ocorre aproximadamente em tempo real (25 caracteres por segundo). Use o endpoint /v1/voices para verificar a disponibilidade atual.
Tratamento de erros HTTP
Se a síntese falhar, você receberá um código de erro HTTP padrão. O corpo da resposta indicará o motivo técnico da falha na geração do áudio.
Retorno de saldo em falhas
Solicitações com falha são gratuitas. Se a síntese não concluir, o valor correspondente é devolvido integralmente ao seu saldo. Isso garante que você não pague por áudio não entregue.
Gerenciamento de vozes e modelos
Os endpoints de listagem permitem verificar em tempo real quais vozes, idiomas e formatos estão disponíveis para sua integração, sem necessidade de consulta externa.
Endpoint GET /v1/voices
Retorna a lista completa de vozes disponíveis, seus idiomas suportados e preços. Use este endpoint para validar a seleção de voz antes da síntese.
Endpoint GET /v1/models
Exibe os modelos de síntese ativos (tts-1 e tts-1-hd), ambos utilizando o mesmo motor de voz e preço por caractere.
Listagem de idiomas e formatos
Consulte os 23 idiomas suportados e os formatos de áudio aceitos (mp3, wav, opus, flac, pcm). Defina o parâmetro language explicitamente para textos em latim não ingleses.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Sua voz transmite autoridade e objetividade, mantendo o foco no conteúdo informativo sem distrações emocionais excessivas.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- Python documentation
- TRON developer hub: TRC-20
- FFmpeg documentation
- W3C WAI: making audio and video accessible
- IETF RFC 7845: Ogg Opus
- MDN: Web Speech API
- ISO 639 language codes
- LibriTTS-R paper (arXiv 2305.18802)
- OpenAI API reference: create speech
- LibriTTS-R corpus (OpenSLR 141)
- Creative Commons Attribution 4.0
