Guia de Integração com a API de Texto para Voz

Por Equipe editorial Locutor.io · Atualizado 2026-11-18

Esta documentação técnica explica como integrar a API de síntese de voz Locutor.io em fluxos de trabalho de produção de rádio e publicidade. Você aprenderá a autenticar, enviar textos e receber arquivos de áudio prontos para locução, com exemplos concretos de integração via cURL e OpenAI SDK.

O guia cobre desde a configuração inicial até o tratamento de erros e limites de uso, focado em criadores de conteúdo que precisam de vozes profissionais. Aqui você encontra os endpoints, formatos de áudio disponíveis e como ajustar parâmetros como velocidade e idioma para atender aos rigorosos padrões de qualidade editorial e publicitária.

Guia de Integração com a API de Texto para Voz

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.mp3

Python (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
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

Autenticação e Chave API

Ilustração de onda sonora para: 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

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

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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

Integração com OpenAI SDK

Formatos de Saída de Áudio

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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 nova e felix para 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.

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

Mais neste site