Documentação técnica da API de narração para audioguias

Por Equipe editorial VozViaja · Atualizado 2026-11-19

Esta documentação descreve a integração técnica da API VozViaja para geração de áudio em audioguias e conteúdos museais. Você encontrará os detalhes do endpoint principal, os parâmetros de requisição e os formatos de áudio suportados, permitindo a integração direta no seu pipeline de produção de áudio.

O guia cobre autenticação via chave API, exemplos de uso com cURL e configuração do SDK OpenAI. São abordados também os limites de taxa, tratamento de erros e a lógica de cobrança por caracteres. Este material é direcionado a engenheiros de software e equipes técnicas de agências que necessitam de escalabilidade e consistência linguística.

Documentação técnica da API de narração para audioguias

Perguntas frequentes

Qual é o endpoint para gerar áudio?

O endpoint é POST https://api.okidr.top/v1/audio/speech. Envie o texto em formato JSON no corpo da requisição. O serviço processa o texto e retorna o arquivo de áudio sintetizado diretamente na resposta HTTP, seguindo a estrutura padrão de endpoints de speech.

Posso usar a biblioteca oficial da OpenAI?

Sim. A API aceita o mesmo formato de corpo JSON do endpoint de speech da OpenAI. Para utilizar, altere a propriedade base_url para https://api.okidr.top/v1 e utilize sua chave de API específica do VozViaja nas bibliotecas oficiais da OpenAI.

Como autenticar a requisição?

Inclua o cabeçalho Authorization: Bearer tts-<sua-chave> em cada requisição. Cada conta possui uma chave ativa por vez. Se você emitir uma nova chave, a anterior é invalidada imediatamente, garantindo que apenas a credencial mais recente seja utilizada para acesso à API.

Qual o tamanho máximo do texto?

O limite é de 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos longos, divida o conteúdo em partes menores e junte os arquivos de áudio resultantes. O processamento é sequencial, então textos muito longos podem levar mais tempo para serem gerados.

Quais formatos de áudio estão disponíveis?

Você pode solicitar os formatos mp3, wav, opus, flac ou pcm. Esses formatos são especificados no campo response_format do corpo da requisição JSON. A escolha do formato depende da necessidade de compatibilidade do seu player ou pipeline de produção de áudio.

O que significa o erro 429?

O erro 429 indica que você excedeu o limite de taxa de 60 requisições por minuto por chave. Antes do primeiro recarga, o limite é de 10 requisições por minuto. Aguarde o tempo de expiração do limite ou realize uma recarga para aumentar a capacidade.

A API retorna o áudio em streaming?

Não. A API retorna o arquivo de áudio completo na resposta após o processamento. Não há suporte para streaming, WebSocket ou áudio parcial em tempo real. O tempo de resposta depende do tamanho do texto e da fila de processamento no momento da solicitação.

Posso definir a velocidade da fala?

Sim. O campo speed aceita valores entre 0.25 e 4.0. Isso permite ajustar a velocidade da narração para audioguias, acelerando ou desacelerando a fala conforme necessário para o contexto do museu ou ponto turístico, mantendo a clareza da síntese.

Como especificar o idioma?

Use o campo language com o código ISO do idioma desejado. Se não especificado, o idioma é detectado pelo script (texto latino assume inglês). Para textos em latim fora do inglês, defina explicitamente o idioma para garantir a pronúncia correta pela voz selecionada.

A API retorna metadados do áudio?

A resposta contém o arquivo de áudio binário. Metadados como tempo, caracteres e status são armazenados para faturamento, mas não são retornados no corpo da resposta de síntese. Para acompanhar o uso, consulte o painel da sua conta na página de dashboard.

Existe suporte para SSML?

Não. A API aceita texto simples no campo input. Não há suporte para marcação SSML, dicionários de fonemas ou lexicons de pronúncia personalizados. A entonação e a pausa são controladas apenas pela pontuação do texto enviado e pelos parâmetros de voz e velocidade disponíveis.

Como redefinir minha chave API?

Acesse a página /get-api-key/ em sua conta. Lá você pode emitir uma nova chave a qualquer momento. Ao emitir uma nova chave, a chave anterior é invalidada imediatamente. Isso garante que apenas a credencial mais recente tenha acesso à API.

Primeira solicitação

curl

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

A API exige autenticação via token Bearer para todas as requisições. Você deve obter sua chave de API na página /get-api-key/, disponível após o login com Google ou e-mail. Uma única chave ativa é associada à sua conta.

Utilize a chave no cabeçalho HTTP para identificar sua conta e garantir o acesso aos endpoints. A segurança é gerenciada diretamente pela plataforma, sem necessidade de certificados adicionais.

Como obter a chave

Como obter a chave

Acesse a página /get-api-key/ e faça o login. A chave é exibida imediatamente após a autenticação. Para contas criadas com Google, o crédito de teste de $0,50 é aplicado automaticamente.

  • Acesso via Google ou e-mail + senha
  • Chave exibida na dashboard após login

Header Authorization

Header Authorization

Inclua o header Authorization: Bearer tts-... em todas as requisições POST para https://api.okidr.top/v1/audio/speech. Sem este cabeçalho, a API retorna erro 401.

  • Formato: Bearer tts-sua_chave_aqui
  • Obrigatório para todos os endpoints

Revocação de chave

Você pode emitir uma nova chave a qualquer momento na dashboard. Ao gerar uma nova chave, a anterior é invalidada imediatamente, encerrando todas as conexões ativas com ela.

  • Emissão instantânea na dashboard
  • Chave antiga invalida no mesmo momento

Endpoint Principal

Ilustração de onda sonora para: Endpoint Principal

O endpoint principal processa a síntese de voz. Envie texto e receba um arquivo de áudio binário. A estrutura de requisição é idêntica à da API de speech da OpenAI, permitindo integração direta com bibliotecas existentes.

O processamento é sequencial. Em alta demanda, as requisições aguardam na fila. O tempo médio é de aproximadamente 25 caracteres de texto por segundo gerado, variando conforme o tamanho do input.

Método POST /v1/audio/speech

Utilize o método HTTP POST para o endpoint /v1/audio/speech. A autenticação é feita via header Authorization: Bearer <sua-chave-api>.

O corpo da requisição deve ser JSON. Certifique-se de que o texto não exceda 4096 caracteres. Textos longos devem ser divididos pela aplicação cliente e unidos posteriormente.

  • URL: https://api.okidr.top/v1/audio/speech
  • Método: POST
  • Content-Type: application/json

Body JSON padrão

O payload requer os campos obrigatórios model, input e voice. O campo input aceita strings UTF-8.

Parâmetros opcionais incluem speed (0.25 a 4.0) e language (código ISO). Se language não for especificado, o sistema tenta adivinhar pelo script, mas para texto em latim não-inglês, defina explicitamente.

  • model: "tts-1" ou "tts-1-hd"
  • input: texto até 4096 caracteres
  • voice: um dos 8 presets disponíveis
  • response_format: mp3, wav, opus, flac ou pcm
  • speed: 0.25 a 4.0

Resposta com arquivo de áudio

Sucessos retornam o código 200 com o arquivo de áudio binário no corpo da resposta. O formato depende do campo response_format enviado.

Se a síntese falhar, o crédito é estornado integralmente. Erros de validação ou autenticação retornam códigos 4xx com detalhes em JSON.

Parâmetros de Requisição

Ilustração de onda sonora para: Parâmetros de Requisição

A API aceita texto bruto com limite máximo de 4096 caracteres por requisição. Caracteres incluem espaços e pontuação. Para textos longos, divida o conteúdo e junte os arquivos de áudio gerados.

Cada solicitação deve especificar o modelo 'tts-1' ou 'tts-1-hd', ambos com o mesmo motor de síntese e preço. O idioma pode ser definido via código ISO ou inferido automaticamente, mas é recomendado definí-lo explicitamente para textos em latim não ingleses.

Campo 'input' e limite de caracteres

O campo 'input' recebe a string de texto a ser convertida. O limite técnico é de 4096 caracteres por chamada. Para audioguias de museus com descrições extensas, implemente a lógica de chunking no lado do cliente, dividindo o texto em partes menores e concatenando os arquivos de áudio resultantes.

A codificação de caracteres deve ser UTF-8. Caracteres especiais e acentos são suportados nativamente nos 23 idiomas disponíveis.

  • Limite máximo: 4096 caracteres por requisição
  • Contagem inclui espaços e pontuação
  • UTF-8 recomendado

Campo 'voice' e opções

O campo 'voice' define o timbre da narração. São 8 vozes pré-configuradas, projetadas para diferentes contextos de audioguias.

As vozes femininas incluem 'aria' (narradora clara), 'nova' (energia positiva), 'luna' (contação de histórias) e 'sage' (instrucional). As masculinas são 'felix' (promocional), 'milo' (conversacional), 'atlas' (noticiário neutro) e 'orion' (documentário).

Todas as vozes podem pronunciar qualquer um dos 23 idiomas suportados sem alteração de timbre.

  • aria: narradora clara e quente
  • nova: tom brilhante e dinâmico
  • luna: suave, ideal para histórias
  • sage: calma, instrucional
  • felix: energético, promocional
  • milo: amigável, conversacional
  • atlas: neutro, estilo noticiário
  • orion: grave, estilo documentário

Campo 'response_format'

Defina o formato de saída do áudio. As opções são mp3, wav, opus, flac e pcm.

Para distribuição web e aplicações móveis, o MP3 oferece a melhor relação entre qualidade e tamanho de arquivo. Para processos de pós-produção em estúdio, utilize WAV ou FLAC para perda zero.

O formato PCM é disponível para áudio bruto não comprimido.

  • mp3: compressão com perda, ideal para web
  • wav: áudio sem compressão, alta fidelidade
  • opus: codec moderno, alta eficiência
  • flac: áudio sem perda de qualidade
  • pcm: áudio bruto não comprimido

Exemplo com cURL

Ilustração de onda sonora para: Exemplo com cURL

Utilize o comando cURL para enviar requisições diretamente ao endpoint de síntese. Este método é ideal para testes rápidos e integração em pipelines de automação de audioguias, permitindo a geração imediata de arquivos de áudio a partir de texto narrativo.

O comando deve incluir a chave de autenticação no header e os parâmetros essenciais de modelo, voz e formato. A resposta retorna o arquivo de áudio binário, que pode ser redirecionado para um arquivo local para uso imediato na produção de conteúdo.

Comando básico

Execute a síntese enviando o texto via campo input. Substitua SUA_CHAVE_API pela sua chave real e ajuste o texto de exemplo conforme o roteiro do audioguia.

O comando abaixo demonstra uma requisição padrão para o endpoint de fala, especificando o modelo tts-1 e a voz nova.

  • curl -X POST "https://api.okidr.top/v1/audio/speech" \ -H "Authorization: Bearer SUA_CHAVE_API" \ -H "Content-Type: application/json" \ -d "{\"model\": \"tts-1\", \"input\": \"Bem-vindo ao museu.\", \"voice\": \"nova\", \"response_format\": \"mp3\"}"

Especificação de formato

Defina explicitamente o formato de saída via response_format. Para audioguias web, o MP3 é recomendado por seu tamanho reduzido. Para gravações de alta fidelidade, utilize WAV ou FLAC.

O formato PCM é útil para processamento adicional, enquanto o OPUS oferece compressão eficiente. O formato escolhido deve ser compatível com o player de áudio final do seu aplicativo ou site.

Tratamento de erro

Se a requisição falhar, o servidor retornará um código HTTP de erro (4xx ou 5xx) e uma mensagem JSON descritiva. Verifique se a chave API está correta e se o texto não excede 4096 caracteres.

Requisições falhas não consomem crédito da sua conta. Se um erro ocorrer, o valor correspondente será devolvido automaticamente ao seu saldo.

Integração com SDK OpenAI

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

O SDK oficial do OpenAI pode ser reutilizado ajustando apenas a URL base para https://api.okidr.top/v1. Isso permite integrar a geração de audioguias diretamente no pipeline de produção de áudio, mantendo a mesma estrutura de chamadas de API já conhecida pela maioria dos desenvolvedores.

A configuração exige a definição do campo base_url para https://api.okidr.top/v1 e a passagem da chave API no cabeçalho de autorização. Esse ajuste garante que as requisições sejam roteadas corretamente para nossa infraestrutura, sem necessidade de alterações no código principal da aplicação.

Configuração de base_url

Defina a variável base_url para https://api.okidr.top/v1. Isso direciona todas as chamadas para a infraestrutura VozViaja. A chave de autenticação deve ser passada no header Authorization: Bearer <sua-chave>.

Use a classe OpenAI do SDK para Python ou Node.js. Ajuste o endpoint base para garantir que o método audio.speech seja executado corretamente contra nossa API. Não é necessário modificar outros parâmetros da biblioteca.

Uso da biblioteca oficial

Invoque client.audio.speech.create() com os parâmetros padrão: model, input, voice e response_format. O SDK lida com a serialização JSON e o envio do arquivo de áudio resultante.

Certifique-se de que o objeto de configuração inclua a chave API válida. O SDK gerencia automaticamente o cabeçalho de autorização, facilitando a integração contínua no pipeline de produção de conteúdo narrado.

Compatibilidade de métodos

A API segue o mesmo formato de solicitação do endpoint de fala da OpenAI. Métodos como POST são suportados. O corpo da requisição aceita campos como input (texto), voice (preset) e speed.

Nenhuma adaptação complexa é necessária. O SDK oficial interpreta os parâmetros corretamente, permitindo que você gere arquivos de áudio em MP3, WAV, OPUS ou FLAC conforme especificado no campo response_format.

Integração com SDK OpenAI

Formatos de Áudio Suportados

Ilustração de onda sonora para: Formatos de Áudio Suportados

A API oferece cinco formatos de saída para atender às diferentes exigências de armazenamento e reprodução dos seus audioguias. A escolha do formato depende do equilíbrio entre qualidade de áudio, tamanho do arquivo e compatibilidade com os dispositivos dos visitantes dos museus.

Todos os formatos são gerados a partir do mesmo motor de síntese, garantindo consistência na voz e na entonação, independentemente da compressão aplicada.

MP3 para web

O formato MP3 é ideal para distribuição via web e aplicativos móveis devido ao seu equilíbrio entre qualidade e tamanho reduzido. É amplamente compatível com todos os players de áudio modernos e navegadores, facilitando a integração em aplicativos de turismo e visitantes.

Utilize este formato para audioguias que serão transmitidos via streaming ou download em redes móveis, onde a largura de banda pode ser limitada.

  • Compatível com a maioria dos dispositivos móveis e web.
  • Tamanho de arquivo otimizado para transmissão rápida.
  • Qualidade sonora adequada para narração em ambientes internos e externos.

WAV para alta fidelidade

O formato WAV oferece áudio sem perda de qualidade, ideal para arquivos master ou para ambientes onde a fidelidade sonora é crítica. Este formato é perfeito para arquivos de áudio que serão usados em sistemas de som de alta qualidade nos museus.

Recomendado para gravações que exigem máxima clareza e detalhe, especialmente em espaços acusticamente tratados.

  • Áudio sem compressão lossy.
  • Ideal para arquivos master ou playback em sistemas de alta fidelidade.
  • Tamanho de arquivo maior, mas qualidade máxima.

OPUS e FLAC

O OPUS é um formato eficiente para streaming de baixa latência, enquanto o FLAC oferece compressão sem perda, similar ao WAV, mas com arquivos menores. Ambos são úteis para casos de uso específicos que exigem alta qualidade com eficiência de armazenamento.

Escolha o OPUS para eficiência de compressão ou FLAC para arquivamento de áudio de alta qualidade sem o overhead do WAV.

  • OPUS: eficiente para streaming de baixa latência.
  • FLAC: compressão sem perda, menor que WAV.
  • Opções flexíveis para diferentes necessidades de qualidade e tamanho.

Limites e Rate Limiting

Ilustração de onda sonora para: Limites e Rate Limiting

A API impõe um limite de 60 requisições por minuto por chave de API. Antes da primeira recarga, esse limite é reduzido para 10 requisições por minuto. Esse controle garante a estabilidade do serviço durante picos de geração de áudio para audioguias.

60 requisições por minuto

Cada chave API permite até 60 solicitações de síntese em um intervalo de 60 segundos. Para contas sem recarga, o limite inicial é de apenas 10 requisições por minuto. Isso é suficiente para testes, mas insuficiente para produção em larga escala sem financiamento.

  • Limite padrão: 60 req/min
  • Limite trial: 10 req/min
  • Contagem por chave API

Fila de processamento

As requisições são processadas sequencialmente. Se o limite for atingido ou o servidor estiver ocupado, novas solicitações entram em uma fila interna. O tempo de geração varia conforme o texto, mas o processamento garante que cada áudio seja completo antes da próxima entrega.

Códigos de erro HTTP

O status 429 indica que o limite de taxa foi excedido. Aguarde e tente novamente. O status 401 indica autenticação inválida ou expirada. Verifique seu header Authorization. Outros erros retornam descrições claras no corpo JSON para facilitar o debug da integração.

Tratamento de Erros

Ilustração de onda sonora para: Tratamento de Erros

A API retorna códigos HTTP padrão para indicar falhas, como 400 para parâmetros inválidos ou 401 para chaves expiradas. Cada resposta inclui uma mensagem clara que detalha o campo afetado, permitindo correções rápidas no pipeline de áudio.

O tratamento adequado de erros garante que seu sistema não perca caracteres faturados. Entender a estrutura da resposta JSON facilita a implementação de retentativas automáticas para erros transitórios de rede.

Erros de validação

Requisições com texto excedendo 4096 caracteres ou formato inválido geram erro 400. O corpo da resposta indica o campo específico, como 'input' ou 'voice', permitindo ajustes imediatos na geração de audioguias.

  • Código HTTP 400 Bad Request
  • Mensagem detalhada no JSON de resposta
  • Validação de tamanho e formato de voz

Erros de autenticação

Chaves inválidas ou expiradas resultam em erro 401. Como apenas uma chave está ativa por conta, a revogação imediata garante que requisições subsequentes falharão até a emissão de uma nova chave na página de configuração.

  • Código HTTP 401 Unauthorized
  • Chave única ativa por conta
  • Revogação instantânea ao emitir nova chave

Retorno de crédito em falha

Se a síntese falhar antes da conclusão, o crédito correspondente é devolvido integralmente. Isso evita custos com arquivos de áudio incompletos ou corrompidos, mantendo a precisão da fatura de caracteres processados.

  • Crédito devolvido em falha de síntese
  • Não há cobrança para áudio inválido
  • Registro de status no painel de uso

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Em museus históricos, a fidelidade e a clareza são prioritárias.

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

Mais neste site