Guia de Integração da API de Texto para Fala

Por Equipe editorial LocDub Studio · Atualizado 2026-11-19

Esta documentação técnica apresenta o guia de integração da API de Texto para Fala da LocDub Studio, projetada especificamente para agências de localização e freelancers que necessitam de narrações rápidas e consistentes. Aqui você encontrará exemplos práticos para gerar áudio sintetizado com custo previsível por caractere, sem surpresas em faturas.

O conteúdo abrange desde a obtenção da chave API até a integração com SDKs populares, incluindo exemplos em Python e curl. Você aprenderá a configurar vozes, idiomas e formatos de saída, além de entender os limites de taxa e o tratamento de erros. Tudo baseado em fatos técnicos reais para sua implementação imediata.

Guia de Integração da API de Texto para Fala

Perguntas frequentes

Como obtenho a chave API?

Acesse a página /get-api-key/ e faça login com Google ou email. O sistema exibe sua chave única no formato tts-.... Você pode emitir uma nova chave a qualquer momento; a anterior é invalidada imediatamente. Cada conta por site mantém apenas uma chave ativa para autenticação via cabeçalho Authorization: Bearer.

Posso usar o SDK oficial da OpenAI?

Sim. A API segue o mesmo formato de requisição do endpoint de fala da OpenAI. Basta alterar o base_url para https://api.superfishing.info/v1 e usar sua chave de API. Isso permite utilizar os SDKs oficiais da OpenAI diretamente, facilitando a integração sem necessidade de bibliotecas proprietárias adicionais.

Qual o limite de caracteres por pedido?

Cada requisição aceita até 4096 caracteres no campo input. Para textos maiores, você deve dividi-los em partes dentro desse limite e unir os arquivos de áudio resultantes. Caracteres incluem espaços e pontuação. O processamento é sequencial, então textos longos podem levar mais tempo para serem gerados.

O que significa o código de erro 429?

O código 429 indica que você excedeu o limite de taxa de 60 requisições por minuto por chave. Antes da primeira recarga, o limite é de 10 requisições por minuto. Aguarde o reset do contador ou realize uma recarga para aumentar seu limite de requisições por minuto.

Como defino o idioma da voz?

Use o campo language com o código ISO do idioma desejado. Se não for definido, o idioma é inferido pelo script (texto latino assume inglês). Para textos em latim que não sejam inglês, defina explicitamente o idioma. O sistema suporta 23 idiomas específicos para síntese.

Posso usar múltiplas vozes em um único pedido?

Não. Cada requisição POST aceita apenas um valor no campo voice, selecionando uma das 8 vozes disponíveis. Para usar múltiplas vozes, envie requisições separadas para cada trecho de texto correspondente à voz desejada e junte os arquivos de áudio gerados posteriormente.

A API retorna áudio em streaming?

Não. A API retorna o arquivo de áudio completo na resposta após a síntese. Não há suporte para streaming, WebSocket ou áudio parcial em tempo real. O cliente deve aguardar o processamento completo para receber o arquivo no formato solicitado (mp3, wav, opus, flac ou pcm).

Como formatar o JSON da requisição?

Envie um POST para /v1/audio/speech com o corpo JSON contendo model (tts-1 ou tts-1-hd), input (texto), voice (nome da voz), response_format e opcionalmente speed e language. Use autenticação Bearer. Exemplo: `{"model": "tts-1", "input": "Olá", "voice": "nova", "response_format": "mp3"}`.

As vozes mudam de preço?

Não. O preço é fixo em $10 por 1 milhão de caracteres, independente da voz ou modelo escolhido (tts-1 ou tts-1-hd usam o mesmo motor e preço). O custo é baseado apenas na quantidade de caracteres processados, incluindo espaços e pontuação, com cobrança precisa por uso.

Posso usar a API em produção imediatamente?

Sim. Após criar uma conta e obter a chave na página /get-api-key/, você pode começar a enviar requisições imediatamente. Não há período de aprovação manual. Basta garantir que sua chave esteja ativa e que você tenha saldo suficiente ou crédito de teste válido para iniciar as integrações.

Há suporte para SSML na API?

Não. A API aceita apenas texto simples no campo input. Não há suporte para marcas SSML, dicionários de fonemas ou lexicons personalizados para pronúncia. A formatação de entonação e pausa é controlada apenas pelo modelo de voz e pela velocidade definida no parâmetro speed.

Como funciona a taxa de limites?

O limite é de 60 requisições por minuto por chave API. Antes da primeira recarga, o limite é reduzido para 10 requisições por minuto. Se exceder, você receberá erro 429. O contador se reinicia a cada minuto. Recargas aumentam automaticamente seu limite de requisições por minuto.

Posso usar a API com Node.js?

Sim. Como a API segue o padrão da OpenAI, você pode usar o pacote openai do Node.js. Configure o baseURL para https://api.superfishing.info/v1 e defina a chave de API. Isso permite utilizar as bibliotecas oficiais existentes sem necessidade de criar adaptadores personalizados ou SDKs próprios.

A resposta inclui metadados do áudio?

A resposta principal contém o arquivo de áudio binário ou base64, conforme o formato solicitado. Metadados de uso (tempo, caracteres, status) são mantidos para faturamento na sua conta, mas não são retornados diretamente no corpo da resposta da requisição de síntese. Consulte o painel para detalhes de uso.

Primeira solicitação

curl

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

Acesse a página /get-api-key/ do site para criar sua conta. Você pode se registrar usando login com Google ou fornecendo e-mail e senha. O método de cadastro define se você receberá o crédito de teste gratuito de $0,50 válido por 7 dias.

Criação de conta no site

Criação de conta no site

O registro é imediato e gratuito. Contas criadas com e-mail e senha começam sem crédito de teste, enquanto o login via Google garante o crédito inicial.

Localização da chave API no painel

Localização da chave API no painel

Após o login, o painel exibe sua chave ativa, o saldo atual e o histórico de uso. A interface apresenta também um exemplo pronto de comando cURL para facilitar os primeiros testes.

  • Chave ativa visível no topo do painel
  • Saldo e caracteres restantes atualizados em tempo real

Emissão de nova chave se necessário

Cada conta possui uma única chave ativa. Você pode emitir uma nova chave a qualquer momento. A chave antiga é invalidada instantaneamente, garantindo que apenas a nova seja válida.

Primeira requisição cURL

Ilustração de onda sonora para: Primeira requisição cURL

Envie seu texto para a API e receba o áudio em segundos. Este é o fluxo mínimo para gerar síntese de voz, ideal para validar sua integração antes de processar volumes maiores de locução.

Exemplo de comando POST

Execute o comando abaixo no terminal para enviar uma solicitação direta. Substitua SUA_CHAVE_AQUI pela chave fornecida no seu painel e ajuste o texto no campo input conforme sua necessidade de dublagem.

Body JSON com parâmetros

O corpo da requisição deve ser enviado como application/json. Defina o modelo (tts-1 ou tts-1-hd), o voice (ex: nova), o input (máximo 4096 caracteres) e o response_format desejado. O idioma é opcional, mas recomendado para textos em latim que não sejam inglês.

Interpretação da resposta

Uma resposta 200 OK contém o arquivo de áudio binário diretamente no corpo da resposta. Se houver erro, o servidor retorna um código de status HTTP e um JSON explicando o problema, como 401 para chave inválida ou 429 para limite de taxa excedido.

Integração com SDK OpenAI

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

A API LocDub Studio segue o formato exato do endpoint de fala da OpenAI. Isso permite usar as bibliotecas oficiais sem reescrever a lógica de integração, apenas ajustando a URL base.

Essa compatibilidade facilita a migração de projetos existentes e mantém a consistência nos fluxos de trabalho de agências de localização que já utilizam ferramentas baseadas no ecossistema OpenAI.

Alteração do base_url

Para integrar, basta apontar o cliente para https://api.superfishing.info/v1 em vez do endpoint padrão. Isso direciona todas as requisições para a infraestrutura da LocDub Studio mantendo a estrutura de endpoints idêntica.

Uso das mesmas bibliotecas oficiais

Utilize as bibliotecas oficiais da OpenAI (Python, Node.js, etc.) sem necessidade de wrappers personalizados. A classe principal de síntese de áudio aceita a configuração customizada de URL nativamente.

Exemplo de código Python

Instale a biblioteca e configure o cliente com sua chave Bearer. O código abaixo demonstra como inicializar o cliente apontando para a API da LocDub Studio e gerar o áudio.

```python from openai import OpenAI client = OpenAI( base_url="https://api.superfishing.info/v1", api_key="tts-sua-chave-aqui" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Texto de teste para locução." ) response.stream_to_file("output.mp3") ```

Parâmetros de voz e idioma

Ilustração de onda sonora para: Parâmetros de voz e idioma

O endpoint GET /v1/voices retorna os 8 vozes disponíveis, todas baseadas em gravações licenciadas. Você pode usar qualquer voz para qualquer idioma suportado, o que facilita a consistência em projetos de localização.

O campo language aceita códigos ISO opcionais. Se não definido, o sistema tenta adivinhar o idioma, mas para textos em latim fora do inglês, especifique o código para evitar erros de pronúncia.

Lista dos 8 presets disponíveis

Escolha entre vozes femininas e masculinas para adaptar o tom da narração.

As vozes são geradas a partir de gravações licenciadas e carregam uma marca d'água inaudível que indica o áudio como sintético.

  • Aria: narradora clara e quente
  • Nova: voz brilhante e animada
  • Luna: suave, ideal para histórias
  • Sage: calma, instrucional
  • Felix: energética, para promoções
  • Milo: amigável e conversacional
  • Atlas: neutra, estilo noticiário
  • Órion: profunda, para documentários

Definição de idioma ISO

O parâmetro language aceita códigos como 'pt', 'en' ou 'de'.

Sem essa especificação, textos em alfabeto latino são padrão para inglês.

Controle de velocidade

Ajuste a velocidade de fala entre 0.25 e 4.0 usando o campo speed.

Valores padrão mantêm um ritmo natural; aumente para agilizar narrações longas ou diminua para maior clareza.

Formatos de saída suportados

Ilustração de onda sonora para: Formatos de saída suportados

O formato de saída é escolhido via parâmetro response_format. Cada tipo atende a uma necessidade técnica específica, desde armazenamento eficiente até processamento em tempo real.

Selecione o formato adequado conforme o pipeline de pós-produção ou a infraestrutura de reprodução do seu projeto.

MP3 para compactação

Formato de áudio com compressão lossy, ideal para reduzir o tamanho dos arquivos sem perder inteligibilidade. É a escolha padrão para a maioria das integrações web e aplicativos móveis, garantindo carregamento rápido e consumo mínimo de largura de banda.

WAV para alta qualidade

Formato de áudio sem compressão, preservando a fidelidade original da síntese. Utilize este formato quando a qualidade de áudio cruza for prioritária, como em gravações profissionais ou arquivos de masterização que não serão comprimidos posteriormente.

Opus, FLAC e PCM disponíveis

Opus oferece compressão eficiente para streaming de voz. FLAC fornece compressão sem perda de dados, mantendo a qualidade original com arquivos menores que WAV. PCM retorna áudio bruto não comprimido, ideal para processamento imediato em pipelines de áudio.

Todos os formatos são especificados no campo response_format da requisição JSON.

Formatos de saída suportados

Limites e cotas

Ilustração de onda sonora para: Limites e cotas

O limite de taxa é de 60 requisições por minuto por chave. Antes da primeira recarga, esse limite é de 10 requisições por minuto. Requests são processados sequencialmente; sob carga, podem entrar em fila.

60 requisições por minuto

Cada chave API permite 60 requisições por minuto. Após a primeira recarga de saldo, o limite aumenta para 60 req/min. Antes da primeira recarga, o limite é de 10 req/min. As requisições são processadas em sequência e podem aguardar na fila.

Limite de 4096 caracteres por pedido

O campo input suporta até 4096 caracteres, incluindo espaços e pontuação. Exceder este limite gera erro na síntese.

Tratamento de textos longos

Para textos maiores, divida o conteúdo em partes de até 4096 caracteres. Gere o áudio para cada parte e junte os arquivos resultantes. O tempo de geração é aproximadamente real-time.

  • Divida o texto em chunks de 4096 caracteres
  • Envie requisições separadas para cada chunk
  • Concatene os arquivos de áudio gerados

Autenticação e segurança

Ilustração de onda sonora para: Autenticação e segurança

A autenticação na API LocDub Studio é feita exclusivamente via token Bearer. Cada requisição POST para geração de áudio deve incluir o cabeçalho Authorization: Bearer tts-SEU_TOKEN. Sem este cabeçalho, a API retorna erro 401.

Cabeçalho Authorization Bearer

Transmita sua chave única no cabeçalho de cada solicitação. O formato é Bearer tts-..., conforme gerado no painel. Isso garante que apenas sua conta possa consumir créditos.

Uma chave ativa por conta

Cada conta possui apenas uma chave válida por vez. Isso simplifica a gestão de segurança em projetos de localização, evitando conflitos de permissão entre múltiplos tokens ativos simultaneamente.

Revogação instantânea de chave

A qualquer momento, você pode emitir uma nova chave no painel. A chave antiga é invalidada imediatamente, garantindo que acessos não autorizados sejam bloqueados sem espera.

Tratamento de erros comuns

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

Para garantir que sua integração funcione sem interrupções, é essencial entender como a API responde a falhas comuns. O sistema retorna códigos HTTP padrão junto com mensagens claras para que você possa depurar rapidamente.

Erro 401: chave inválida

Esse erro indica que o token fornecido no cabeçalho Authorization está ausente, expirado ou incorreto. Verifique se sua chave começa com tts- e se você está usando a chave ativa do seu painel.

Erro 429: limite excedido

O limite de 60 requisições por minuto foi atingido. Aguarde o reset do minuto ou integre lógica de espera (retry) no seu código. Lembre-se que novos contas começam com apenas 10 req/min.

Retorno de erros JSON

Todas as falhas retornam um objeto JSON estruturado contendo o campo error com message e type. Use essas informações para tratar exceções programaticamente em vez de exibir erros genéricos ao usuário.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Utilize a mesma predefinição em todos os idiomas quando possível.

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. MDN: Web Speech API
  3. IETF RFC 7845: Ogg Opus
  4. OpenAI API reference: create speech
  5. curl documentation
  6. LibriVox public-domain audiobooks
  7. LibriTTS-R corpus (OpenSLR 141)
  8. FFmpeg documentation
  9. Python documentation
  10. openai-python on GitHub
  11. TRON developer hub: TRC-20
  12. Tether (USDT)

Mais neste site