Perguntas frequentes
Qual o modelo de voz padrão?
O modelo padrão é o tts-1. Ele utiliza o mesmo motor de síntese e possui o mesmo preço do modelo tts-1-hd. Ambos aceitam os mesmos parâmetros de entrada, como texto, voz, formato de resposta e velocidade, garantindo compatibilidade imediata com sua integração.
Posso usar o SDK do Python?
Sim, você pode usar o SDK da OpenAI para Python. Basta alterar a propriedade base_url para https://api.play33l.com/v1 e utilizar a chave da VozSpot. Isso permite que você continue usando a mesma estrutura de código familiar, apenas redirecionando as requisições para nossa API, sem precisar de bibliotecas proprietárias adicionais.
Como defino o idioma?
Você pode definir o idioma explicitamente passando o código ISO no campo language da requisição. Se não for informado, o sistema tenta adivinhar o idioma com base no script do texto; textos em latim são padronizados como inglês. Para textos em latim não ingleses, defina o idioma manualmente.
O que é tts-1-hd?
O tts-1-hd é o segundo modelo disponível, oferecendo a mesma qualidade de engine do tts-1. Ambos têm o mesmo preço e funcionalidade. A escolha entre eles é baseada apenas na preferência técnica, sem diferença de custo ou limitações técnicas entre os dois modelos na API.
Qual o tamanho máximo do texto?
O limite é de 4096 caracteres por requisição. Para textos mais longos, você deve dividi-los em partes dentro desse limite e juntar os arquivos de áudio resultantes. Isso garante que cada solicitação seja processada eficientemente, mantendo a qualidade do áudio gerado para cada segmento de texto enviado.
Como obtenho a lista de vozes?
Faça uma requisição GET para o endpoint /v1/voices. Esta rota retorna informações sobre as vozes disponíveis, incluindo idiomas, formatos de áudio suportados e preços. É a maneira oficial e programática de descobrir quais vozes estão ativas e quais parâmetros são necessários para cada uma.
A API retorna streaming?
Não. A API retorna o arquivo de áudio completo após a síntese ser concluída. Não há suporte para streaming, WebSockets ou áudio parcial em tempo real. Você receberá o arquivo final no formato solicitado (mp3, wav, opus, flac ou pcm) apenas quando o processamento estiver totalmente finalizado.
Posso enviar áudio em vez de texto?
Não. A VozSpot é uma API de texto para voz (TTS). O campo input aceita apenas texto. Não há endpoint para enviar arquivos de áudio para processamento ou conversão. O foco é exclusivamente na geração de áudio a partir de strings de texto enviadas via JSON.
O que fazer em caso de erro 429?
O erro 429 indica que você atingiu o limite de 60 requisições por minuto. Aguarde até que o contador de taxa seja resetado. Se estiver usando uma chave nova sem recarga, o limite é de 10 requisições por minuto. Reduza a frequência de suas chamadas ou aguarde o período de carência.
A chave expira?
A chave de API não tem data de expiração. Ela permanece válida indefinidamente até que você decida emitir uma nova. Ao gerar uma nova chave, a anterior é invalidada imediatamente. Não há custo de manutenção ou renovação anual para manter sua chave ativa e acessível à API.
Posso usar múltiplas chaves?
Não. Cada conta possui apenas uma chave ativa por vez. Se você gerar uma nova chave, a anterior deixa de funcionar instantaneamente. Isso simplifica a gestão de acesso e segurança. Você pode emitir uma nova chave a qualquer momento para revogar o acesso da chave anterior imediatamente.
O SDK da OpenAI é oficial?
Não. O SDK da OpenAI é um cliente genérico que funciona conosco porque seguimos o mesmo formato de endpoint. Não somos afiliados à OpenAI. Usamos o SDK apenas por conveniência técnica, alterando a URL base. A implementação e o suporte dependem da biblioteca padrão, não de nós.
Como testar a API localmente?
Use cURL ou qualquer cliente HTTP para enviar uma requisição POST para https://api.play33l.com/v1/audio/speech. Inclua sua chave Bearer e o texto no corpo JSON. A resposta conterá o arquivo de áudio binário. Você pode usar o exemplo de cURL disponível na página /get-api-key/ para começar.
Primeira solicitação
curl
curl https://api.play33l.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.play33l.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.play33l.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 | |
|---|---|
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 e Chave API
Para integrar a VozSpot, você precisa de uma chave de API válida. Acesse /get-api-key/ para visualizá-la, gerá-la ou revogá-la. Cada conta possui apenas uma chave ativa por site.
A autenticação é feita via cabeçalho HTTP padrão, garantindo compatibilidade imediata com seus scripts existentes sem necessidade de bibliotecas adicionais complexas.
Onde encontrar sua chave
Sua chave de API é gerenciada na página de configuração da conta. Lá, você verá o identificador único que começa com 'tts-'. É o único segredo necessário para autorizar suas requisições de síntese.
- Acesse /get-api-key/ após o login
- Visualize o token ativo iniciado por 'tts-'
Cabeçalho Authorization
Inclua o cabeçalho HTTP padrão em todas as requisições. O formato deve seguir a especificação Bearer para garantir que o endpoint reconheça sua identidade e vincule os custos à sua conta correta.
- Authorization: Bearer tts-SEU_TOKEN_AQUI
Emissão de nova chave
Se sua chave for comprometida ou você quiser separar ambientes, emita uma nova chave diretamente pelo painel. A chave antiga deixa de funcionar imediatamente, sem necessidade de esperar propagação ou reiniciar serviços.
Endpoint Principal
O coração da nossa API é um único ponto de entrada otimizado para conversão de texto em áudio. Ao enviar uma requisição POST com o texto e as configurações desejadas, você recebe imediatamente o arquivo de áudio sintetizado pronto para uso em suas campanhas.
Esta abordagem centralizada simplifica a integração técnica, permitindo que equipes de produção foquem na qualidade do roteiro enquanto nossa infraestrutura cuida da renderização eficiente de cada pedido.
Método POST
Utilize o método HTTP POST para enviar seus dados. Este método é padrão para envio de payloads complexos e garante que textos longos ou com caracteres especiais sejam processados corretamente sem limitações de tamanho de URL.
URL do endpoint
Dirija suas requisições para a URL base da API. A estrutura segue o padrão do endpoint de fala da OpenAI, facilitando a integração com ferramentas existentes.
Formato JSON
O corpo da requisição deve ser codificado em JSON. Inclua os campos obrigatórios como model, input e voice. O sistema valida a estrutura antes do processamento, retornando erros claros se algum parâmetro estiver ausente ou inválido.
- Conteúdo: application/json
- Campos: model, input, voice, response_format, speed
Exemplo de Requisição cURL
Para começar, envie uma requisição POST para o endpoint de fala. O corpo da solicitação deve ser em JSON, contendo o texto a ser sintetizado, o modelo de voz escolhido e o formato de áudio desejado. Este é o fluxo básico para gerar qualquer spot ou narração.
Comando básico
Utilize cURL para enviar seu texto diretamente. Substitua sua-chave-aqui pela sua chave API real e ajuste os parâmetros conforme sua necessidade de produção.
- curl -X POST "https://api.play33l.com/v1/audio/speech"
- -H "Authorization: Bearer sua-chave-aqui"
- -H "Content-Type: application/json"
- -d '{"model": "tts-1", "input": "Olá, este é um teste.", "voice": "nova"}'
Parâmetros obrigatórios
O campo input aceita até 4096 caracteres. Espaços e pontuação contam como caracteres. Você deve definir o model como "tts-1" ou "tts-1-hd" e escolher uma das oito vozes disponíveis no endpoint de listagem.
- model: tts-1 ou tts-1-hd
- input: string de texto (máx. 4096 chars)
- voice: ex. nova, aria, felix, atlas
- response_format: mp3, wav, opus, flac ou pcm
Resposta esperada
O sucesso retorna o arquivo de áudio binário diretamente no corpo da resposta HTTP. Se a síntese falhar, você receberá um código de erro JSON e a cobrança será estornada, garantindo que você não pague pelo que não funcionou.
Uso com SDK da OpenAI
O VozSpot é compatível com o SDK da OpenAI, permitindo que você utilize bibliotecas já conhecidas sem precisar aprender uma nova sintaxe. A única configuração necessária é ajustar o base_url para apontar para a infraestrutura da VozSpot.
Essa abordagem simplifica a integração, pois você mantém a mesma estrutura de código, alterando apenas a URL de base e a chave de autenticação para usar o endpoint da VozSpot.
Configuração base_url
Defina o base_url do seu cliente para https://api.play33l.com/v1. Isso direciona todas as chamadas para a API de texto para voz da VozSpot, mantendo a compatibilidade com o formato de resposta da OpenAI.
Mudança de cliente
Atualize sua chave API para a chave válida da VozSpot (formato tts-...). O SDK lidará com a autenticação via cabeçalho Authorization: Bearer, garantindo que as requisições sejam processadas corretamente.
Compatibilidade total
Utilize os métodos padrão do SDK, como Audio.speech, passando os parâmetros model, input, voice e response_format. A estrutura de dados permanece idêntica, facilitando a migração de projetos existentes.
- Use
model='tts-1'oumodel='tts-1-hd'para definir a qualidade. - Defina
voicecom um dos 8 presets disponíveis. - Especifique
response_formatpara escolher entre mp3, wav, opus, flac ou pcm.
Parâmetros da Requisição
Configure os parâmetros essenciais para transformar texto em áudio com precisão. Cada campo define a qualidade, o idioma e a velocidade da geração, garantindo que o resultado final atenda exatamente ao roteiro da sua campanha.
Modelo tts-1 e tts-1-hd
O campo model aceita apenas "tts-1" ou "tts-1-hd". Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço de $0,01 por 1.000 caracteres. Não há diferença de qualidade auditiva entre as duas opções; a escolha é puramente técnica para compatibilidade com SDKs.
Campo input e texto
O campo input recebe o texto que será convertido. O limite é de 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos longos, divida-o em partes menores e junte os arquivos de áudio resultantes posteriormente.
- Use caracteres em branco como separadores se necessário.
Voice e velocidade
Defina a voz com um dos 8 presets disponíveis (ex: aria, felix). Ajuste a speed entre 0.25 e 4.0 para adaptar o ritmo da narração ao vídeo ou rádio. Se omitido, o idioma é detectado automaticamente, mas é recomendável defini-lo explicitamente para textos em latim não ingleses.

Formatos de Saída
Escolha o formato de áudio que melhor se adapta ao seu fluxo de produção, equilibrando qualidade e peso do arquivo. A API oferece cinco opções para atender desde arquivos leves até masterização profissional.
Todos os formatos são gerados via POST para /v1/audio/speech e podem ser selecionados no campo response_format.
MP3 e WAV
O MP3 é a escolha padrão para a maioria dos casos, garantindo compatibilidade universal com players de rádio e plataformas digitais. O WAV oferece áudio sem perda de qualidade, ideal para edições posteriores em estúdio.
Use MP3 para distribuição rápida e WAV quando precisar de máxima fidelidade para mixagem.
- MP3: leve e universal
- WAV: qualidade sem perda
Opus e FLAC
O Opus oferece alta compressão com qualidade excelente. O FLAC é sem perda e mantido, garantindo integridade auditiva total sem o peso excessivo do WAV.
Formatos modernos para eficiência ou preservação máxima.
- Opus: compressão eficiente
- FLAC: sem perda de qualidade
PCM para debug
O formato PCM retorna áudio bruto, sem compactação. É útil principalmente para testes técnicos e depuração, pois permite inspecionar o sinal de áudio em sua forma mais pura.
Ideal para verificar a exatidão da síntese antes da codificação final.
- PCM: áudio bruto para testes
Limites e Erros
Entender os limites de uso é essencial para planejar campanhas de rádio e spots publicitários sem interrupções. A API possui regras claras de taxa e tamanho que garantem a estabilidade do serviço durante a geração de áudio.
Respeitar esses limites evita erros de 429 e garante que seus áudios sejam entregues no formato esperado. Abaixo estão os detalhes técnicos para uma integração fluida.
60 requisições por minuto
Cada chave API permite até 60 requisições por minuto. É importante notar que, antes da primeira recarga, o limite é de apenas 10 requisições por minuto.
Limite de caracteres
Cada requisição suporta até 4.096 caracteres no campo input. Textos longos devem ser divididos em partes menores e unidos posteriormente.
Códigos de erro comuns
Requisições falhas são gratuitas e o valor é devolvido integralmente. Erros de taxa (429) indicam que você atingiu o limite de requisições por minuto.
- 400: Erro de validação nos parâmetros enviados
- 401: Chave de API inválida ou ausente
- 429: Limite de requisições por minuto excedido
- 500: Erro interno no processamento de áudio
Listagem de Vozes
Use o endpoint GET para obter metadados atualizados sobre vozes e formatos disponíveis. Esta é a forma programática de verificar o catálogo antes de iniciar a produção.
O endpoint retorna informações estruturadas que você pode integrar diretamente no seu painel de controle ou workflow de produção.
Endpoint /v1/voices
Acesse GET /v1/voices para listar todas as vozes disponíveis. A resposta inclui o ID da voz, o idioma suportado e o formato padrão.
Esses dados permitem que você valide a disponibilidade antes de enviar uma requisição de síntese.
- GET /v1/voices retorna JSON com lista de vozes
- Inclui metadados de idioma e formato suportado
- Atualização em tempo real da infraestrutura
Filtros por idioma
O endpoint não suporta filtragem nativa por parâmetro, mas a resposta contém o campo de idioma para cada voz.
Você pode filtrar localmente no seu código usando os 23 idiomas suportados, como português, inglês ou espanhol.
- 23 idiomas suportados na lista
- Filtro recomendado via código do cliente
- Idioma definido automaticamente se não especificado
Listagem de modelos
O endpoint GET /v1/models lista os modelos de síntese disponíveis, como tts-1 e tts-1-hd.
Use esta informação para configurar corretamente o campo 'model' na sua requisição de áudio.
Os modelos compartilham a mesma infraestrutura de geração de voz.
- GET /v1/models retorna lista de modelos
- Suporte a tts-1 e tts-1-hd
- Mesma engine de síntese base
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Transforme o silêncio do ar em uma experiência sonora que conecta marcas e pessoas com emoção e criatividade.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
