Perguntas frequentes
Qual o formato padrão da resposta da API?
A API retorna o arquivo de áudio diretamente no corpo da resposta HTTP. Você pode escolher o formato desejado (mp3, wav, opus, flac ou pcm) enviando o campo response_format na requisição JSON. Não há formatação JSON para o áudio em si, apenas o binário do arquivo gerado.
Posso usar o SDK da OpenAI com esta API?
Sim, a estrutura de requisição é idêntica à da OpenAI. Basta alterar o base_url do SDK para https://api.cw05.info/v1 e utilizar sua chave de API. Isso permite integrar a narração automática em seus fluxos de treinamento utilizando a mesma biblioteca que já conhece.
Como especificar o idioma Português?
Envie o código ISO pt no campo language da requisição. Embora o sistema tente adivinhar o idioma pelo script, definir explicitamente o português garante que a voz correta seja aplicada, especialmente se o texto contiver palavras de outros idiomas ou nomes próprios que possam confundir o reconhecimento.
O que acontece se o texto for maior que 4096 caracteres?
Você deve dividir o texto em partes de até 4096 caracteres e enviar cada parte em requisições separadas. Em seguida, junte os arquivos de áudio gerados para criar o arquivo final de treinamento. Cada requisição é processada individualmente, respeitando os limites de caracteres por chamada.
A chave da API expira automaticamente?
Não há expiração automática para a chave ativa. Você possui uma única chave por conta, que pode ser renovada a qualquer momento. Ao emitir uma nova chave, a anterior é invalidada instantaneamente, garantindo que apenas a credencial mais recente esteja em uso no seu sistema de RH.
Posso usar HTTPS apenas?
A API opera sobre HTTPS no endpoint https://api.cw05.info/v1. Todas as requisições, incluindo o envio da chave de autenticação, são protegidas por transporte seguro, garantindo a integridade dos dados enviados para a geração de áudio corporativo.
Há limite de tamanho de arquivo de áudio?
Não há limite específico de tamanho de arquivo imposto pela API. O limite aplica-se ao texto de entrada (4096 caracteres por requisição). O tamanho do arquivo final depende da duração do áudio gerado e do formato escolhido (mp3, wav, etc.), sem restrições de armazenamento no serviço.
Como debugar erros de autenticação?
Verifique se o cabeçalho Authorization: Bearer tts-... está correto e se a chave está ativa. Se a chave foi renovada, a anterior deixa de funcionar imediatamente. Certifique-se de que sua conta possui saldo suficiente, pois erros de pagamento podem ocorrer, embora requisições falhas sejam gratuitas.
Primeira solicitação
curl
curl https://api.cw05.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.cw05.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.cw05.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 e Chave
Para utilizar a API de narração corporativa, você deve primeiro obter sua chave de acesso única na página /get-api-key/. Essa credencial é vinculada diretamente ao seu saldo e aos limites de uso da equipe de RH ou L&D.
A autenticação é feita enviando o cabeçalho Authorization: Bearer <sua-chave> em todas as requisições. Mantenha essa chave segura, pois ela autoriza o consumo dos seus caracteres.
Obtenha sua chave no painel
Acesse o painel em /get-api-key/ para visualizar sua chave ativa, o saldo atual e o histórico de uso. A chave é emitida automaticamente após o cadastro via Google ou e-mail, permitindo que você comece a testar a narração imediatamente.
Cabeçalho Authorization Bearer
Inclua o parâmetro de autenticação em cada chamada POST para /v1/audio/speech. O formato padrão é aceito pelos SDKs oficiais, facilitando a integração com os sistemas de gestão de treinamento da sua empresa.
Revoque chaves antigas instantaneamente
Caso haja qualquer suspeita de uso indevido ou mudança na equipe, você pode emitir uma nova chave a qualquer momento no painel. A chave anterior deixa de funcionar instantaneamente, garantindo que apenas a equipe atualizada tenha acesso à API.
Endpoint de Síntese
A síntese de voz corporativa ocorre via endpoint POST na rota /v1/audio/speech. Este é o único ponto de entrada necessário para converter textos de treinamento em áudio.
O sistema processa as requisições sequencialmente. Em cargas altas, os pedidos podem aguardar na fila antes da geração, garantindo que cada áudio seja criado com consistência.
POST /v1/audio/speech
Envie uma requisição HTTP POST para https://api.cw05.info/v1/audio/speech. Este endpoint recebe o texto e as configurações de voz para iniciar o processo de narração.
O endpoint aceita o corpo JSON conforme detalhado abaixo e retorna o arquivo de áudio sintetizado diretamente na resposta.
Corpo JSON com parâmetros
O corpo da requisição deve conter os campos obrigatórios: model, input e voice. O campo input aceita até 4096 caracteres por requisição.
Você pode especificar opcionalmente a velocidade, o formato de resposta e o idioma ISO para garantir a precisão na narração multilíngue.
O campo model aceita 'tts-1' ou 'tts-1-hd', utilizando o mesmo motor de síntese.
- 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: número entre 0.25 e 4.0
- language: código ISO opcional
Retorno do arquivo de áudio
A resposta contém o arquivo de áudio sintetizado no formato solicitado. O arquivo é gerado com base no texto fornecido e na voz selecionada.
Se a síntese falhar, a cobrança não é aplicada e o valor é devolvido integralmente ao seu saldo.
O áudio retornado não é armazenado; ele é entregue diretamente na resposta e usado apenas para sua integração.
Parâmetros de Entrada
Para integrar a narração automática aos seus fluxos de L&D, é necessário estruturar corretamente o corpo da requisição JSON. A API processa texto puro, então o foco deve estar na precisão do conteúdo enviado para garantir a fidelidade da voz sintetizada.
Cada parâmetro define como o áudio será gerado. O texto de entrada limita-se a 4096 caracteres por chamada, o que exige divisão de textos longos. A escolha da voz e do modelo determina o tom e a qualidade final do material de treinamento.
Campo input (texto máximo 4096 chars)
O campo input recebe o texto que será convertido em áudio. O limite é de 4096 caracteres por solicitação, incluindo espaços e pontuação. Para treinamentos corporativos extensos, é necessário dividir o conteúdo em partes menores e unir os arquivos resultantes.
Exceder esse limite gera erro na requisição. Planeje a segmentação do seu script de treinamento para manter a consistência narrativa entre as partes geradas.
- Máximo: 4096 caracteres por requisição
- Inclui espaços e pontuação na contagem
- Textos longos requerem divisão manual ou lógica de split
Campo voice (8 presets disponíveis)
Escolha entre 8 vozes pré-definidas para diferentes contextos de RH. Opções femininas incluem aria (narradora clara), nova (enerética), luna (storytelling) e sage (instrucional). Para vozes masculinas, há felix (promo), milo (conversacional), atlas (notícias) e orion (documentário).
Cada voz é baseada em gravações licenciadas e garante consistência de marca. Todas as vozes falam os 23 idiomas suportados, permitindo multilinguismo sem troca de voz.
- Aria, Nova, Luna, Sage (mulheres)
- Felix, Milo, Atlas, Orion (homens)
- Vozes fixas, sem clonagem personalizada
Campo model (tts-1 ou 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. A escolha não altera a capacidade de geração, apenas o formato de saída (HD ou padrão).
Use tts-1-hd para arquivos de alta definição em treinamentos que exigem maior fidelidade sonora, embora o custo seja idêntico. A diferença é imperceptível na velocidade de processamento.
- Valores válidos: tts-1, tts-1-hd
- Mesmo preço e mesmo motor
- Escolha baseada apenas na preferência de formato
Formatação e Idioma
Configure o formato de saída para equilibrar qualidade e peso do arquivo. As opções incluem MP3, WAV, OPUS, FLAC e PCM, adequados para diferentes sistemas de LMS e players corporativos.
Defina o idioma explicitamente para garantir a pronúncia correta, especialmente em textos multilíngues ou com termos técnicos específicos.
O sistema detecta automaticamente o script (latim, cirílico, etc.) e assume inglês para textos em latim não especificados. Para outros idiomas, defina o código ISO.
Se não definido, o idioma é inferido, mas para textos em português ou espanhol usando alfabeto latino, especifique 'pt' ou 'es' para evitar a pronúncia em inglês.
response_format (mp3, wav, opus, flac, pcm)
Escolha o formato que melhor se integra à sua infraestrutura de treinamento. MP3 é universal; WAV e FLAC oferecem alta fidelidade; OPUS é um formato eficiente.; PCM é bruto.
O formato não afeta a qualidade da voz, apenas o tamanho do arquivo e a compatibilidade com seu player ou LMS.
Sinalização de language (ISO)
Use o parâmetro language com o código ISO 639-1 (ex: 'pt', 'en', 'es'). Isso garante que a voz use a entonação e a pronúncia corretas.
Essencial para textos mistos ou quando o script latino poderia ser ambíguo (ex: espanhol vs. inglês).
- Códigos suportados: ar, zh, da, nl, en, fi, fr, de, el, he, hi, it, ja, ko, ms, no, pl, pt, ru, es, sw, sv, tr
Detecção automática de script
Se language não for fornecido, o sistema detecta o script. Textos em latim são tratados como inglês por padrão.
Para português, espanhol ou outros idiomas latinos, defina language explicitamente para evitar pronúncia em inglês.
Scriptos cirílico, árabe, etc., são detectados automaticamente para atribuir o idioma correto.
Controle de Velocidade
A velocidade de narração é ajustável entre 0.25 e 4.0, permitindo adaptar o ritmo do áudio às necessidades específicas dos materiais de treinamento. Esse controle garante que o conteúdo seja compreensível e adequado ao contexto, seja para uma leitura detalhada ou para uma revisão rápida.
Range de 0.25 a 4.0
O parâmetro speed aceita valores decimais dentro desse intervalo. Valores mais baixos (< 1.0) desaceleram a voz, ideal para textos técnicos ou novos funcionários. Valores mais altos (> 1.0) aceleram a narração, útil para revisões rápidas de processos.
- Padrão: 1.0
- Mínimo: 0.25
- Máximo: 4.0
Velocidade real aproximada
Em velocidade padrão (1.0), a geração ocorre em tempo real aproximado, consumindo cerca de 25 caracteres de texto por segundo de áudio. Para textos longos, o tempo total de síntese equivale à duração do áudio final.
Impacto na geração de áudio
Alterar a velocidade não afeta a qualidade da voz, apenas a duração. Textos muito longos são divididos em partes de até 4096 caracteres. Sob carga, as requisições podem aguardar na fila, mas a velocidade ajustada mantém a proporção exata do áudio gerado.

Exemplo com cURL
Para validar a integração rapidamente, utilize a linha de comando diretamente no terminal do seu ambiente de desenvolvimento. Este comando envia uma solicitação simples para a API, permitindo verificar se a autenticação e a configuração estão corretas antes de integrar ao sistema de treinamento.
A resposta conterá o arquivo de áudio bruto, pronto para ser reproduzido ou armazenado. Este método é ideal para testes unitários e validação de parâmetros como voz e idioma.
Comando básico de teste
Execute o comando abaixo substituindo SEU_TOKEN pela chave obtida no painel. O exemplo utiliza a voz nova com texto padrão.
```bash curl -X POST https://api.cw05.info/v1/audio/speech \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Bem-vindo ao treinamento", "voice": "nova"}' \ -o audio_test.mp3 ```
Este comando demonstra a estrutura mínima necessária para uma solicitação válida, utilizando o modelo padrão.
Substituição de chave e texto
Substitua SEU_TOKEN pela chave real fornecida em https://cw05.info/get-api-key/. Altere o campo input para o texto do módulo de treinamento desejado, respeitando o limite de 4096 caracteres. A voz nova é recomendada para narrativas claras e motivadoras, mas você pode escolher entre os 8 presets disponíveis.
Se necessário, ajuste o model para tts-1-hd para maior qualidade ou defina o language explicitamente para evitar detecção automática.
Salvamento do arquivo de resposta
O parâmetro -o audio_test.mp3 salva o áudio gerado diretamente em um arquivo local. Você pode alterar a extensão para .wav, .opus, .flac ou .pcm conforme o formato necessário para seu LMS.
Verifique se o arquivo foi criado corretamente e reproduza-o para confirmar a integridade do áudio e a velocidade de narração.
- Formatos suportados: mp3, wav, opus, flac, pcm
- Arquivo gerado contém marca d'água inaudível de síntese
- Tempo de geração aproximado: 25 caracteres/segundo
Uso com SDK OpenAI
O SDK oficial da OpenAI funciona com nossa API basta alterar a URL base para https://api.cw05.info/v1 e fornecer sua chave de API VozCorporativa. Isso permite que equipes de RH utilizem bibliotecas já consolidadas em seus ambientes de desenvolvimento sem necessidade de adaptações complexas.
Configuração do base_url
Inicialize o cliente passando a URL base correta. Isso direciona todas as chamadas para nossa infraestrutura enquanto mantém a compatibilidade com os métodos padrão da biblioteca.
- base_url: 'https://api.cw05.info/v1'
- api_key: 'sua_chave_aqui'
Mudança de endpoint
O endpoint de geração de áudio permanece /v1/audio/speech. A estrutura do JSON enviado é idêntica à esperada pela OpenAI, garantindo que scripts existentes funcionem imediatamente.
Reutilização de código existente
Códigos que consomem vozes para treinamento corporativo podem ser migrados rapidamente. Basta ajustar a configuração inicial e validar a entrega dos arquivos de áudio em MP3 ou WAV.
Limites e Erros
O limite padrão é de 60 requisições por minuto por chave. Antes da primeira recarga, esse limite cai para 10 por minuto.
Se você exceder o limite, o serviço retorna um código 429. Isso é esperado durante picos de geração de áudio para treinamentos.
60 requisições por minuto
Cada chave de API permite até 60 chamadas à API por minuto. Esse limite garante estabilidade para equipes de RH que geram múltiplos áudios simultaneamente.
Antes da primeira recarga de saldo, o limite é reduzido para 10 requisições por minuto. Isso ajuda a prevenir o esgotamento acidental do crédito de teste.
- Limite padrão: 60 req/min
- Limite pré-recarga: 10 req/min
Código de erro 429 para limites
Quando o limite é atingido, o servidor responde com HTTP 429 (Too Many Requests). Isso indica que você deve aguardar antes de enviar mais texto.
Não há penalidade adicional. Basta esperar que o contador de requisições resete no minuto seguinte.
Retorno de erro em JSON
Erros são retornados como objetos JSON contendo detalhes da falha. Isso facilita o tratamento programático em scripts Python ou JavaScript.
Exemplos incluem erros de validação de parâmetros ou problemas de autenticação. Sempre verifique o campo 'error' na resposta.
- Formato: JSON
- Campos: 'error', 'message', 'code'
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Formatos como Opus e FLAC também estão disponíveis para casos específicos que exigem compressão eficiente sem perda.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
