Documentação da API de Texto para Fala para Desenvolvedores

Por Equipe editorial Wasp Voices · Atualizado 2026-11-19

Esta documentação explica como integrar nossa API de texto para fala no fluxo de desenvolvimento do seu jogo indie. Você aprenderá a enviar texto e receber arquivos de áudio para diálogos de NPCs ou narração de missões, usando a mesma estrutura da API de speech da OpenAI.

Começamos com autenticação e exemplos práticos em cURL, depois detalhamos os parâmetros de voz, formato e velocidade. Se preferir, mostramos como usar o SDK oficial da OpenAI apenas alterando a URL base. Tudo para você gerar áudio de qualidade com integração simples e código limpo.

Documentação da API de Texto para Fala para Desenvolvedores

Perguntas frequentes

Como obtenho minha API Key?

Acesse /get-api-key/ e faça login com Google ou e-mail e senha. A chave é exibida na página e usada no cabeçalho Authorization: Bearer tts-.... Cada conta possui uma chave ativa por site. Você pode emitir uma nova a qualquer momento; a antiga é invalidada imediatamente.

Qual o formato da resposta da API?

A resposta é um arquivo de áudio binário no formato solicitado (mp3, wav, opus, flac ou pcm). O cabeçalho Content-Type indica o tipo. A resposta é o arquivo de áudio binário; não há wrapper JSON.

Posso usar a biblioteca oficial da OpenAI?

Sim. A API aceita o mesmo formato de requisição da OpenAI. Basta alterar o base_url para https://api.wasp33.info/v1 e usar sua chave Wasp Voices. As SDKs oficiais funcionam alterando apenas a URL base, facilitando a integração em projetos existentes.

O que acontece se exceder o limite de requisições?

Você receberá um erro de rate limit (429). O limite é de 60 requisições por minuto por chave (10 antes do primeiro depósito). As requisições são processadas em fila, então pode haver espera. Não há penalidade financeira, apenas atraso no processamento até que a taxa permita.

Como especificar um idioma específico?

Envie o código ISO do idioma no campo language da requisição (ex: pt-BR). Se omitido, o sistema tenta adivinhar pelo script (texto latino assume inglês). Para textos em português ou outros idiomas com script latino, defina language explicitamente para garantir a pronúncia correta.

A API retorna áudio em streaming?

Não. A API retorna o arquivo completo após o processamento. Não há streaming, WebSocket ou áudio parcial. Para jogos, você deve esperar a resposta completa ou implementar buffering se usar HTTP 1.1 chunked, mas o endpoint não suporta streaming nativo como algumas alternativas.

Posso enviar texto com acentos?

Sim. O campo input aceita UTF-8, suportando acentos e caracteres especiais. O limite é de 4096 caracteres por requisição, contando espaços e pontuação. A síntese processa corretamente textos em português, espanhol, francês e outros idiomas suportados, mantendo a integridade da pronúncia.

Qual a diferença entre tts-1 e tts-1-hd?

Ambos usam o mesmo motor de síntese e têm o mesmo preço: $10 por 1 milhão de caracteres. A escolha entre tts-1 e tts-1-hd é apenas para compatibilidade com SDKs da OpenAI, mas não altera a qualidade, o preço ou o formato do áudio gerado.

Como lidar com textos longos?

Divida o texto em partes de até 4096 caracteres. Envie cada parte separadamente via POST e, em seguida, junte os arquivos de áudio resultantes. Isso garante que o limite de caracteres seja respeitado. O processamento é sequencial, então textos muito longos podem levar mais tempo.

A API suporta SSML?

Não. A API aceita apenas texto simples no campo input. Não há suporte para SSML, tags de emoção ou dicionários de pronúncia personalizados. Você deve usar a pontuação e a divisão de frases para controlar a entonação, já que não há marcação estruturada avançada.

Posso usar a API em jogos mobile?

Sim. A API é acessível via HTTP/HTTPS de qualquer lugar. Você pode integrar a chamada em seu jogo ou usar um servidor intermediário para esconder a chave. Não há SDK mobile dedicado, mas a biblioteca HTTP padrão ou a SDK OpenAI funcionam perfeitamente.

Onde encontro mais exemplos de código?

A página /get-api-key/ inclui um exemplo curl pronto para uso. Para outras linguagens, use a biblioteca oficial da OpenAI com o base_url ajustado para https://api.wasp33.info/v1. Consulte a documentação técnica para detalhes sobre o formato JSON e os parâmetros de voz e velocidade.

Como resetar minha API Key?

Acesse /get-api-key/ e emita uma nova chave. A chave antiga é invalidada imediatamente. Isso é útil se você suspeitar que a chave foi exposta. Você pode fazer isso quantas vezes precisar, mantendo o mesmo saldo e histórico de uso na conta.

A API retorna metadados do áudio?

Não. A resposta contém apenas o arquivo de áudio binário. Metadados como tempo, caracteres usados e status são mantidos para faturamento na sua conta, mas não são incluídos na resposta HTTP. Você deve rastrear o uso e o custo com base no seu próprio registro.

Primeira solicitação

curl

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

Autenticação

Ilustração de onda sonora para: Autenticação

Para usar a API da Wasp Voices, você precisa de uma chave de API única. Ela é gerada ao criar sua conta na página /get-api-key/. Cada conta mantém apenas uma chave ativa por vez, o que simplifica a gestão para projetos indie.

API Key

API Key

Sua chave começa com o prefixo tts- e é usada para identificar sua conta e debitar o saldo. Ela é visível apenas na área de membros após o login com Google ou email.

Header Authorization

Header Authorization

Envie sua chave no cabeçalho HTTP de cada requisição. Use o formato padrão Bearer para garantir que o endpoint aceite sua solicitação de síntese.

  • Header: Authorization: Bearer tts-seu-chave-aqui

Gerar Nova Chave

Se sua chave for exposta, você pode gerar uma nova imediatamente na dashboard. A chave antiga deixa de funcionar instantaneamente, garantindo segurança sem downtime.

Endpoints Principais

Ilustração de onda sonora para: Endpoints Principais

Os endpoints principais permitem gerar áudio, listar vozes disponíveis e verificar os modelos suportados. A autenticação é feita via header Authorization: Bearer <sua-chave>.

Use POST /v1/audio/speech para converter texto em áudio. Consulte GET /v1/voices para ver as 8 vozes e formatos, e GET /v1/models para confirmar as opções de modelo.

POST /v1/audio/speech

Endpoint principal para síntese de áudio. Recebe texto até 4096 caracteres e retorna o arquivo de áudio binário na resposta.

  • Endpoint: POST https://api.wasp33.info/v1/audio/speech
  • Requisita áudio em formatos como mp3, wav, opus, flac ou pcm
  • Resposta contém o binário do áudio ou erro JSON

GET /v1/voices

Retorna lista de vozes, idiomas suportados e formatos disponíveis. Útil para construir interfaces de seleção dinâmicas nos seus jogos.

  • Endpoint: GET https://api.wasp33.info/v1/voices
  • Lista 8 vozes (aria, nova, luna, sage, felix, milo, atlas, orion)
  • Inclui metadados sobre idiomas e formatos compatíveis

GET /v1/models

Retorna os modelos disponíveis (tts-1 e tts-1-hd), ambos com o mesmo motor e preço, facilitando a escolha técnica.

  • Endpoint: GET https://api.wasp33.info/v1/models
  • Retorna lista de modelos ativos e suas configurações

Parâmetros de Requisição

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

Para enviar texto à API, você deve estruturar o corpo da requisição JSON com os parâmetros essenciais. O campo input aceita strings de até 4096 caracteres, que incluem espaços e pontuação. Para textos longos, divida o conteúdo em partes menores e junte os arquivos de áudio gerados.

input (texto)

O parâmetro input recebe a string de texto que será sintetizada. Cada solicitação processa no máximo 4096 caracteres. Se o diálogo do NPC ou a narração exceder esse limite, divida o texto em chunks e concatene os arquivos resultantes.

voice (predefined)

Escolha entre 8 vozes pré-definidas, como aria, nova ou atlas. Cada voz tem uma personalidade distinta, ideal para diferentes tipos de NPCs ou narradores. O idioma é opcional; se não especificado, o sistema tenta adivinhar pelo script, mas defina explicitamente para textos em latim não ingleses.

  • aria: narradora clara e quente
  • nova: voz brilhante e animada
  • atlas: neutra, ideal para notícias

response_format

Defina o formato de saída do áudio entre mp3, wav, opus, flac ou pcm. MP3 é eficiente para transmissão, enquanto WAV e FLAC preservam a qualidade sem compressão. O formato PCM oferece áudio cru, útil para processamento posterior em engines de jogos.

Formatos de Áudio

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

Escolher o formato de áudio certo impacta diretamente o tamanho do arquivo final e a qualidade sonora do seu jogo. A API oferece cinco opções, desde compressão leve até áudio bruto, garantindo que você tenha o controle total sobre o pipeline de áudio.

Cada formato serve a um propósito diferente na produção de jogos indie. Entender as diferenças técnicas ajuda a otimizar o tamanho do build e a experiência de escuta dos jogadores sem perder tempo em conversões desnecessárias.

MP3

O formato MP3 é ideal para a maioria dos diálogos de NPCs e narrações. Ele oferece uma boa relação entre qualidade e tamanho reduzido, facilitando o streaming ou o carregamento rápido dentro do jogo.

Use MP3 quando o tamanho do pacote do jogo for uma prioridade, mas a qualidade de áudio ainda precisa ser clara e natural para os jogadores.

  • Tamanho de arquivo menor
  • Qualidade de áudio consistente
  • Ampla compatibilidade

WAV

O WAV é um formato de áudio sem compressão, ideal para gravações de alta fidelidade. Ele preserva todos os detalhes do áudio original, sem perda de qualidade.

Utilize WAV para missões críticas onde a clareza é essencial, mesmo que isso resulte em arquivos maiores.

  • Sem perda de qualidade
  • Alta fidelidade
  • Arquivos maiores

OPUS, FLAC, PCM

OPUS e FLAC oferecem compressão com perda e sem perda, respectivamente, proporcionando eficiência sem sacrificar a qualidade. PCM é o formato de áudio bruto, sem compressão, ideal para processamento posterior.

Escolha OPUS para streaming eficiente, FLAC para arquivamento de alta qualidade, e PCM quando você precisa de dados de áudio brutos para processamento adicional.

  • OPUS: Compressão eficiente
  • FLAC: Sem perda de qualidade
  • PCM: Áudio bruto

Exemplo com cURL

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

Use cURL para testar a integração diretamente no terminal. Este comando envia o texto para a API e recebe o áudio processado.

Comando Básico

Execute esta requisição POST, substituindo SUA_CHAVE pela sua API key. O endpoint aceita JSON com o texto e as configurações de voz.

  • curl -X POST https://api.wasp33.info/v1/audio/speech \
  • -H "Authorization: Bearer SUA_CHAVE" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Olá mundo", "voice": "aria"}'

Resposta JSON

A API retorna o arquivo de áudio binário diretamente na resposta. Este formato facilita o parsing imediato em scripts de jogos.

  • "audio": "base64_string_here..."
  • "id": "audio_123"
  • "created": 1698765432

Download do Áudio

Para salvar o arquivo localmente, redirecione a saída para um arquivo. O formato será definido pelo parâmetro response_format na requisição.

  • curl [comando] -o fala.mp3
Exemplo com cURL

Integração com SDK OpenAI

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

A API segue o mesmo formato de requisição do endpoint de fala da OpenAI, o que permite reutilizar os SDKs oficiais com apenas uma configuração de base_url. Isso simplifica a integração em projetos de jogos existentes, evitando a necessidade de escrever parsers personalizados para JSON e áudio binário.

Alterar base_url

Para usar o SDK, basta apontar o cliente para o nosso endpoint: https://api.wasp33.info/v1. Isso mantém toda a compatibilidade de campos (model, input, voice, etc.) sem mudanças na lógica de chamada.

Usar Client OpenAI

Utilize o SDK oficial da OpenAI para Python ou Node.js (ou HTTP direto). O objeto OpenAI aceita a URL personalizada via parâmetro base_url no momento da instância.

Exemplo de Código

```python from openai import OpenAI client = OpenAI( base_url="https://api.wasp33.info/v1", api_key="tts-sua-chave-aqui" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Olá, aventureiro. A missão começa agora." ) response.stream_to_file("mission_start.mp3") ```

Limites e Erros

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

A API impõe limites claros para garantir estabilidade durante o desenvolvimento. O texto enviado por solicitação deve ter no máximo 4096 caracteres. Para textos mais longos, como diálogos extensos de NPCs, você deve dividir o conteúdo e juntar os arquivos de áudio gerados.

4096 Caracteres

Cada chamada de síntese processa até 4096 caracteres, incluindo espaços e pontuação. Se sua missão ou diálogo ultrapassar esse limite, divida o texto em partes menores e concatene os arquivos de áudio resultantes.

60 Req/min

O limite de taxa é de 60 requisições por minuto por chave. Se sua conta é nova e ainda não possui recarga, o limite inicial é de apenas 10 requisições por minuto. Para evitar gargalos, implemente lógica de retry ou agendamento no seu pipeline.

Códigos de Erro

Requisições com falha são gratuitas e o crédito é devolvido integralmente. Use os códigos padrão HTTP para tratar erros de sintaxe, limites excedidos ou autenticação inválida diretamente na sua integração.

Velocidade e Idioma

Ilustração de onda sonora para: Velocidade e Idioma

Ajuste a velocidade da fala com o parâmetro speed, que aceita valores entre 0.25 e 4.0. Para diálogos de NPCs ou narração de missões, valores próximos de 1.0 garantem naturalidade, enquanto velocidades maiores podem ser úteis para leituras rápidas de logs.

O parâmetro language aceita códigos ISO opcionais. Definir o idioma explicitamente evita ambiguidades, especialmente em textos curtos ou com idiomas misturados, garantindo a pronúncia correta dos seus diálogos.

O sistema detecta automaticamente o idioma com base no script do texto. Se o language não for definido, textos em latino padrão são interpretados como inglês.

Parâmetro speed

Você pode controlar a velocidade da síntese usando o campo speed na requisição. Os valores válidos variam de 0.25 (muito lento) a 4.0 (muito rápido).

Para jogos indie, manter a velocidade em 1.0 é o padrão recomendado para diálogos de NPCs. Valores extremos podem tornar a fala artificial ou difícil de entender em missões narrativas.

  • Mínimo: 0.25
  • Máximo: 4.0
  • Padrão: 1.0

Parâmetro language

Defina o idioma explicitamente usando um código ISO (ex: pt, en, ja). Isso é crucial quando o contexto do texto não deixa claro o idioma esperado.

Nossas 8 vozes suportam 23 idiomas. Se a detecção falhar, o parâmetro language garante que o áudio gerado corresponda à língua do diálogo do seu jogo.

Idiomas não listados, como vietnamita ou tailandês, não são suportados, mesmo que o texto esteja em caracteres compatíveis.

  • Suporta 23 idiomas (qualquer voz fala qualquer idioma)
  • Qualquer voz fala qualquer idioma
  • Vietnamita e Tailandês não suportados

Detecção Automática

Se você omitir o parâmetro language, a API tenta adivinhar o idioma com base nos caracteres do texto input.

Textos em alfabeto latino são padronizados como inglês por padrão. Para textos em português, espanhol ou francês sem o campo language, o resultado pode ser uma pronúncia em inglês.

Recomendamos sempre definir language para textos não anglófonos para evitar erros de pronúncia em diálogos críticos.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. A variação mantém o jogador engajado e imerso na narrativa do jogo.

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. ISO 639 language codes
  3. Node.js documentation
  4. openai-node on GitHub
  5. openai-python on GitHub
  6. IETF RFC 7845: Ogg Opus
  7. MDN: Web Speech API
  8. Python documentation
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. FFmpeg documentation
  11. LibriTTS-R corpus (OpenSLR 141)
  12. Creative Commons Attribution 4.0

Mais neste site