Integração Rápida da API de Texto para Voz com Exemplos

Por Equipe editorial VozSpot · Atualizado 2026-11-18

Esta documentação explica como integrar a API de texto para voz do VozSpot em poucos minutos, focando em agilidade para agências de publicidade e produtores de rádio. Você aprenderá a enviar textos e receber arquivos de áudio profissionais via JSON, sem complexidade desnecessária. O guia cobre desde a autenticação até a geração de spots, que podem levar alguns segundos para frases curtas e mais tempo para textos longos.

Aqui você encontrará exemplos práticos em cURL e instruções para usar o SDK da OpenAI com nossa base URL personalizada. Entenda os parâmetros de voz, formatos de saída e limites de uso para criar suas campanhas sem surpresas. Tudo o que você precisa para automatizar a narração está aqui, de forma clara e direta.

Integração Rápida da API de Texto para Voz com Exemplos

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.mp3

Python (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
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

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

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

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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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' ou model='tts-1-hd' para definir a qualidade.
  • Defina voice com um dos 8 presets disponíveis.
  • Especifique response_format para escolher entre mp3, wav, opus, flac ou pcm.

Parâmetros da Requisição

Ilustração de onda sonora para: 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.

Parâmetros da Requisição

Formatos de Saída

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

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. Python documentation
  3. TRON developer hub: TRC-20
  4. curl documentation
  5. IETF RFC 7845: Ogg Opus
  6. LibriVox public-domain audiobooks
  7. MDN: Web Speech API
  8. FFmpeg documentation
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. W3C WAI: making audio and video accessible
  11. Tether (USDT)
  12. Node.js documentation

Mais neste site