Perguntas frequentes
Qual é o endpoint principal da API?
O endpoint principal é POST https://api.getbb7.com/v1/audio/speech. Você envia texto em formato JSON e recebe um arquivo de áudio. A estrutura da requisição é idêntica à da OpenAI, facilitando a integração com sistemas existentes.
Como autentico minhas requisições?
Utilize o cabeçalho Authorization: Bearer tts-... com sua chave ativa. Cada conta possui apenas uma chave por vez. Se você gerar uma nova chave, a anterior deixa de funcionar imediatamente, garantindo segurança no acesso à API.
Posso usar o SDK da OpenAI?
Sim. Como o formato da requisição é o mesmo, você pode usar os SDKs oficiais da OpenAI. Basta alterar o base_url para https://api.getbb7.com/v1 e utilizar sua chave de API específica do Locutor.io.
Qual o limite de caracteres por requisição?
O campo input aceita até 4096 caracteres por solicitação. Para textos maiores, você deve dividir o conteúdo em partes menores e juntar os arquivos de áudio gerados. Espaços e pontuação contam como caracteres.
O que é o parâmetro 'language'?
É um código ISO opcional para especificar o idioma. Se não definido, o sistema tenta adivinhar pelo script. Para textos em latim não ingleses, defina explicitamente, pois o padrão é inglês. Idiomas não listados não são suportados.
Como obter a lista de vozes disponíveis?
Faça uma requisição GET para /v1/voices. Este endpoint retorna informações sobre vozes, idiomas, formatos de áudio e preços. Você também pode consultar /v1/models para detalhes sobre os modelos tts-1 e tts-1-hd.
A API suporta streaming de áudio?
Não. A API retorna o arquivo de áudio completo na resposta após a síntese. Não há suporte para streaming, WebSockets ou áudio parcial em tempo real. O processamento é feito de forma síncrona.
Quais erros HTTP posso receber?
Requisições malformadas ou com caracteres excedentes geram erros. Se a síntese falhar, a cobrança é estornada integralmente. Verifique o status da resposta para confirmar se o áudio foi gerado com sucesso ou se houve falha no processamento.
O áudio gerado é armazenado na API?
Não. O áudio é retornado diretamente na resposta da requisição e não é armazenado em nossos servidores. Apenas metadados da solicitação (tempo, caracteres, status) são mantidos para fins de cobrança e registro.
Posso mudar o formato de saída para WAV?
Sim. O parâmetro response_format aceita mp3, wav, opus, flac e pcm. Você pode escolher o formato mais adequado para seu fluxo de trabalho editorial ou de publicidade ao enviar a requisição de síntese.
Como funciona o limite de 60 requisições por minuto?
O limite é de 60 requisições por minuto por chave (10 por minuto antes do primeiro aporte). Antes do primeiro aporte, o limite é de 10 por minuto. As requisições são processadas em fila; sob carga, pode haver espera na fila de processamento.
O que acontece se o texto for muito longo?
Você deve dividir o texto em partes de até 4096 caracteres. Em seguida, envie cada parte separadamente e junte os arquivos de áudio gerados. Isso garante que o limite de caracteres seja respeitado em cada requisição.
A chave API pode ser revogada?
Sim. Uma nova chave pode ser emitida a qualquer momento. Quando isso acontece, a chave antiga deixa de funcionar imediatamente. Isso permite que você revogue o acesso antigo instantaneamente, sem necessidade de suporte.
Existe taxa de transferência (egress) para downloads?
Não há menção a taxas de transferência ou egress nos fatos do produto. O custo é baseado apenas nos caracteres processados (1 milhão de caracteres por US$ 10). Não há cobrança adicional por download ou largura de banda.
Primeira solicitação
curl
curl https://api.getbb7.com/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.getbb7.com/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.getbb7.com/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
Para utilizar a API de texto para voz, você precisa de uma chave de autenticação válida. Acesse a página /get-api-key/ para criar sua conta ou visualizar sua chave ativa, saldo e histórico de uso.
A chave é um token Bearer que deve ser incluído no cabeçalho de todas as requisições. Ela é vinculada à sua conta e garante o acesso aos recursos de síntese de áudio.
Obtenha sua chave no painel de controle
Acesse /get-api-key/ para registrar-se com Google ou e-mail. O painel exibe sua chave atual, saldo e limites de uso.
- Suporte apenas por e-mail
Formato da chave Bearer token
Inclua o cabeçalho Authorization: Bearer tts-... em suas requisições POST.
A chave é única por conta e deve ser mantida em sigilo.
Emissão de nova chave invalida a anterior
Você pode gerar uma nova chave a qualquer momento pelo painel.
A chave anterior é invalidada instantaneamente, sem transição.
Endpoint Principal: POST /v1/audio/speech
O endpoint principal recebe texto e configurações de síntese, retornando o arquivo de áudio no formato solicitado. A estrutura segue o padrão da API de speech, permitindo integração direta com SDKs existentes via ajuste do base_url.
Para locuções publicitárias, o corpo da requisição define o modelo de voz, o texto a ser convertido e os parâmetros técnicos. Cada chamada processa até 4096 caracteres, gerando o arquivo de áudio sintetizado com as especificações escolhidas.
Envio de texto e parâmetros de voz
Envie um JSON contendo o texto e as preferências de áudio. O sistema processa a solicitação e retorna o arquivo binário na resposta.
Campos obrigatórios: model, input, voice
O campo model aceita "tts-1" ou "tts-1-hd", ambos utilizando o mesmo motor de síntese. O input deve conter o texto da locução, limitado a 4096 caracteres. O voice seleciona um dos oito presets disponíveis, como aria ou atlas.
Esses três parâmetros são essenciais para a geração do áudio. Sem eles, a API não consegue determinar a qualidade, o conteúdo ou a identidade vocal da locução.
- model: "tts-1" ou "tts-1-hd"
- input: texto até 4096 caracteres
- voice: um dos 8 presets disponíveis
Parâmetros opcionais: speed, language, response_format
A velocidade de fala (speed) varia de 0.25 a 4.0, permitindo ajustes dinâmicos para spots publicitários mais rápidos ou narrações calmantes. O idioma (language) pode ser definido por código ISO, evitando a detecção automática incorreta para textos em latim.
O formato de saída (response_format) aceita mp3, wav, opus, flac ou pcm. Escolha mp3 para web, wav para alta fidelidade ou pcm para processamento em tempo real.
Configurar o idioma explicitamente é recomendado para textos em línguas não inglesas que utilizem alfabeto latino, garantindo a pronúncia correta.
- speed: 0.25 a 4.0
- language: código ISO opcional
- response_format: mp3, wav, opus, flac, pcm
Endpoints de Consulta: Vozes e Modelos
A API expõe metadados essenciais para a integração técnica. O endpoint de vozes permite consultar os 8 presets disponíveis e os 23 idiomas suportados, garantindo que o script de integração selecione a voz adequada para o idioma do texto antes do envio.
O endpoint de modelos retorna detalhes técnicos sobre as engines tts-1 e tts-1-hd. Essas informações são críticas para validar a compatibilidade de formato e entender as capacidades base antes de iniciar a produção em massa de áudios para campanhas.
GET /v1/voices para listar vozes e idiomas
Consulte este endpoint para obter a lista completa de vozes e seus metadados, incluindo idiomas suportados. Cada voz possui um nome único (como aria, nova, atlas) e é capaz de falar qualquer um dos 23 idiomas disponíveis, sem necessidade de modelos específicos por idioma.
- Listagem de 8 vozes pré-configuradas com descrições de tom.
- Suporte a 23 idiomas, incluindo português, inglês e espanhol.
- Compatibilidade total: qualquer voz pode falar qualquer idioma listado.
GET /v1/models para detalhes dos modelos
Retorna informações sobre os modelos de síntese disponíveis, atualmente tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de geração e possuem o mesmo preço, diferindo apenas na qualidade de áudio. Este endpoint confirma a estrutura de dados esperada para a requisição de geração.
- Modelos tts-1 e tts-1-hd com mesma engine.
- Mesmo preço por caractere para ambos os modelos.
- Validação de compatibilidade para requisições POST.
Informações de preços e formatos disponíveis
O endpoint de vozes também inclui informações sobre os formatos de áudio suportados: mp3, wav, opus, flac e pcm. Os preços são padrão por caractere processado, e a estrutura de resposta auxilia no cálculo antecipado de custos para grandes volumes de narração.
- Formatos: mp3, wav, opus, flac, pcm.
- Preço fixo por caractere processado.
- Metadados incluem código ISO dos idiomas suportados.
Exemplo de Requisição com cURL
O endpoint principal aceita requisições JSON para gerar áudio sintetizado. A estrutura segue o padrão da API de speech, permitindo controle granular sobre o resultado final.
Utilize cURL para testar rapidamente a integração. O comando abaixo demonstra a configuração mínima necessária para obter um arquivo de áudio válido.
Comando pronto para copiar e colar
Execute o comando abaixo substituindo <SEU_TOKEN> pela sua chave Bearer. Este exemplo gera um arquivo MP3 com a voz 'nova' em português.
Configuração de headers de autorização
O cabeçalho Authorization deve conter o token Bearer seguido da sua chave única. Sem esta credencial, a API retorna erro 401.
Exemplo de corpo JSON completo
O corpo da requisição deve incluir model, input e voice. O campo input aceita até 4096 caracteres. Para textos longos, realize múltiplas requisições.
Integração com OpenAI SDK
Você pode utilizar as bibliotecas oficiais da OpenAI (Node.js, Python, etc.) para interagir com a Locutor.io. A única configuração necessária é alterar a URL base (base_url) para apontar para o endpoint da nossa API, mantendo a estrutura de requisição idêntica.
Isso permite reutilizar seu código existente sem precisar aprender uma nova sintaxe. Basta garantir que o cabeçalho de autorização contenha sua chave Bearer válida.
Alteração do base_url para a API
Configure a variável de ambiente ou o parâmetro de inicialização do SDK para https://api.getbb7.com/v1. Isso redireciona todas as chamadas para nossos servidores, mantendo a compatibilidade com o formato de payload padrão.
Uso dos mesmos métodos da biblioteca OpenAI
Utilize o método audio.speech.create exatamente como faria com a OpenAI. Os campos model, input, voice e response_format são aceitos da mesma forma, facilitando a migração de projetos que já consomem essa API.
Compatibilidade com SDKs oficiais
Qualquer SDK oficial da OpenAI (v1.0.0 ou superior) funciona sem adaptações complexas. Basta garantir que sua chave de API esteja configurada corretamente no cabeçalho Authorization: Bearer tts-... antes de iniciar a geração de áudio.

Formatos de Saída de Áudio
A API permite escolher o formato de áudio ideal para cada etapa do seu projeto editorial. A opção padrão é MP3, que oferece boa compressão para transmissão web.
Para projetos que exigem máxima fidelidade, como masterização de spots de rádio, o formato WAV é a escolha técnica correta. Ele preserva a qualidade original sem perdas de compressão.
Outros formatos atendem a necessidades específicas de integração ou armazenamento.
MP3 para compressão e web
O MP3 é recomendado para a maioria dos casos de uso na web. Ele equilibra tamanho de arquivo e qualidade sonora, sendo ideal para players de áudio online e aplicativos móveis.
Utilize este formato quando a largura de banda for uma consideração ou quando o áudio for reproduzido diretamente no navegador.
- Compatível com todos os players modernos
- Tamanho de arquivo reduzido
- Qualidade auditiva consistente
WAV para alta fidelidade
O formato WAV mantém a qualidade de áudio sem compressão lossy. É a opção preferida para gravações profissionais e pós-produção em estúdio.
Ideal para locutores que necessitam processar o áudio gerado sem introduzir artefatos de compressão adicionais durante a edição.
- Sem perda de qualidade
- Ideal para masterização
- Ampla compatibilidade em DAWs
OPUS, FLAC e PCM para usos específicos
O OPUS oferece excelente compressão. O FLAC é um formato sem perdas, mantendo a qualidade do WAV com menos espaço em disco. O PCM fornece dados de áudio brutos, sem cabeçalhos adicionais, perfeito para processamento programático direto.
Escolha estes formatos apenas se sua pipeline de áudio exigir características específicas de compressão ou processamento de sinal.
- OPUS: alta eficiência de compressão
- FLAC: qualidade sem perdas
- PCM: dados brutos de áudio
Limites e Tratamento de Erros
A API aceita textos de até 4.096 caracteres por chamada. Para narrativas mais longas, o texto deve ser dividido em partes menores e os áudios gerados unidos posteriormente.
Limite de 4096 caracteres por requisição
Cada solicitação POST processa no máximo 4.096 caracteres, incluindo espaços e pontuação. O limite é rígido; excedê-lo resulta em erro na validação do corpo da requisição.
Código de status HTTP em caso de falha
Se a síntese falhar devido a um erro interno ou de formato, o servidor retorna um código de status HTTP indicando o problema. O processo de geração é sequencial, podendo haver espera em fila sob alta carga.
Reembolso automático em erros de síntese
Solicitações que falham não consomem saldo. O valor correspondente à requisição é devolvido integralmente à sua conta, garantindo que você pague apenas pelo áudio gerado com sucesso.
Exemplos de Uso para Rádio e Publicidade
Para spots publicitários, a API processador frases curtas em segundos, permitindo iterações rápidas de teste. Use vozes como nova para anúncios vibrantes ou atlas para tom jornalístico. Cada requisição aceita até 4096 caracteres, suficientes para a maioria dos jingles de 15 a 30 segundos.
Em casos de erros de síntese, a cobrança é estornada integralmente, garantindo que você pague apenas pelo áudio entregue. Essa previsibilidade de custo facilita o orçamento para campanhas de rádio que exigem múltiplas variações de um mesmo texto.
Geração de spots publicitários curtos
A velocidade de geração é ideal para testes A/B de chamadas publicitárias. Com a voz felix, você obtém um tom energético pronto para promos de rádio. O formato MP3 garante compatibilidade com players de áudio.
- Vozes
novaefelixpara tons vibrantes - Formato MP3 para web e rádio
- Testes rápidos sem custo em falhas
Narração de textos longos com split
Para locuções extensas, divida o texto em blocos de 4096 caracteres e una os arquivos resultantes. O áudio gerado mantém a consistência de tom, embora as requisições sejam processadas sequencialmente. Isso evita cortes abruptos em narrativas de produtos ou audiobook.
O limite de caracteres é rígido; excedê-lo retorna erro. A lógica de split deve ser implementada no seu backend para garantir a fluidez da narração final.
- Máximo de 4096 caracteres por requisição
- Processamento sequencial sob carga
- Junte arquivos para narração contínua
Ajuste de velocidade para locuções dinâmicas
Ajuste a velocidade entre 0.25 e 4.0 para adaptar o ritmo à trilha sonora ou ao tempo de spot. Para locuções dinâmicas, velocidades próximas de 1.5 a 2.0 mantêm o engajamento sem perder a clareza da articulação.
Lembre-se que textos mais longos são gerados em tempo real aproximado, mas pequenas variações de velocidade podem afetar o tempo total de entrega em filas de alta demanda.
- Range de velocidade: 0.25 a 4.0
- Ajuste fino para ritmo de locução
- Impacto no tempo de espera sob carga
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. A seleção de idioma é crucial para a precisão da pronúncia, especialmente quando o texto utiliza o alfabeto latino mas não é inglês.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
