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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
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
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

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
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
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.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
