Perguntas frequentes
Qual o formato base da requisição JSON?
A requisição é enviada via POST para o endpoint /v1/audio/speech. O corpo deve conter campos como model, input (texto), voice, response_format e speed. A estrutura é idêntica à da API de speech da OpenAI, facilitando a integração para desenvolvedores que já utilizam esse padrão de consumo, alterando apenas a URL base.
Posso usar a biblioteca oficial da OpenAI?
Sim. Como a forma da requisição é a mesma, você pode usar os SDKs oficiais da OpenAI. Basta alterar o parâmetro base_url para https://api.kohkae789.cc/v1 e utilizar a sua chave de API própria. Isso permite uma migração rápida sem necessidade de reescrever a lógica de consumo.
O que acontece se exceder o limite de requisições?
O limite é de 60 requisições por minuto por chave (10 antes do primeiro recarga). Se exceder, as requisições são processadas em fila ou podem ser recusadas. O processamento é sequencial, então sob carga, as solicitações podem aguardar na fila até que haja capacidade disponível para síntese.
Como especificar uma voz masculina ou feminina?
Escolha entre as 8 vozes disponíveis no campo voice. Femininas: aria, nova, luna, sage. Masculinas: felix, milo, atlas, orion. Cada voz tem um timbre específico, como narrador, conversacional ou documental. O idioma é opcional e pode ser definido explicitamente ou inferido pelo script do texto enviado.
O idioma é detectado automaticamente?
O idioma pode ser detectado automaticamente se não for especificado. Para textos em latim, o padrão é inglês. Para outros idiomas, recomenda-se definir o campo language com o código ISO. Isso garante a pronúncia correta, especialmente para línguas que não usam o alfabeto latino ou têm regras específicas.
Posso enviar texto com mais de 4096 caracteres?
Não diretamente. O limite por requisição é de 4096 caracteres. Para textos maiores, você deve dividir o conteúdo em partes menores, enviar cada parte separadamente e, em seguida, juntar os arquivos de áudio gerados. Isso permite criar áudios longos mantendo a integridade do formato de saída.
O endpoint /v1/voices retorna todos os idiomas?
Não. O endpoint GET /v1/voices retorna as vozes disponíveis, idiomas, formatos e preços. Os idiomas suportados são 23, como inglês, português, espanhol e japonês. Para ver a lista completa de idiomas e vozes, consulte este endpoint ou a documentação de preços e configurações disponíveis na API.
Como revogo minha chave API antiga?
Basta emitir uma nova chave na página da sua conta. A nova chave torna-se ativa imediatamente e a antiga é desativada no mesmo instante. Não há período de transição ou sobreposição. Isso garante que apenas a chave mais recente seja utilizada para autenticação nas requisições subsequentes à API.
Qual a diferença entre tts-1 e tts-1-hd?
Ambos utilizam o mesmo motor de síntese e têm o mesmo preço. A diferença reside apenas na identificação do modelo na requisição. O modelo tts-1-hd indica alta qualidade, mas não há diferença técnica ou de custo em relação ao tts-1. Ambos aceitam os mesmos parâmetros e formatos de saída.
Os formatos PCM e FLAC são recomendados?
Os formatos disponíveis são mp3, wav, opus, flac e pcm. PCM e FLAC são sem perda, ideais para edições profissionais. MP3 e OPUS são compactados. A escolha depende do uso final. Todos os formatos são gerados com a mesma qualidade de voz, variando apenas no tamanho do arquivo e compressão.
Há suporte para SSML na API?
Não. A API não suporta marcação SSML (Speech Synthesis Markup Language). Você deve enviar apenas texto puro. Para controlar pausas ou ênfase, utilize a velocidade (speed) entre 0.25 e 4.0. Não há suporte para dicionários de fonemas ou pronúncia personalizada via marcação XML dentro do corpo da requisição.
O áudio é gerado de forma síncrona ou assíncrona?
O áudio é retornado na resposta da requisição HTTP. O processamento é sequencial, então o tempo de resposta depende da fila. Para textos longos, o tempo é próximo do tempo real de áudio. Não há endpoint assíncrono ou webhook para notificação de conclusão; o arquivo é entregue diretamente na resposta.
Como tratar erros de resposta da API?
Se a síntese falhar, a cobrança é devolvida integralmente. Verifique o código de status HTTP e a mensagem de erro no corpo da resposta. Erros comuns incluem limite excedido ou formato inválido. Tempos de resposta podem variar sob carga. Monitore o status para garantir o processamento.
Posso usar a API para gerar áudio em tempo real?
Não há streaming ou WebSocket para áudio parcial. O áudio é gerado completo e retornado na resposta. Para uso em tempo real, você deve esperar a conclusão da requisição. A latência depende da fila de processamento. Não há suporte para transmissão progressiva do áudio enquanto ele é sintetizado.
Primeira solicitação
curl
curl https://api.kohkae789.cc/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.kohkae789.cc/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.kohkae789.cc/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
A autenticação na Edição Voz utiliza uma única chave ativa por conta, emitida na página /get-api-key/. Basta copiar o token fornecido e incluí-lo no cabeçalho Authorization de suas requisições.
Geração de chave única
Cada conta possui apenas uma chave ativa por site. Ao gerar uma nova chave, a anterior é invalidada imediatamente, garantindo segurança simples sem necessidade de gerenciar múltiplos tokens.
Revogação instantânea
A revogação é imediata. Ao solicitar uma nova chave na interface, a anterior deixa de funcionar no mesmo instante, permitindo resposta rápida a qualquer uso indevido.
Formato do token Bearer
Inclua a chave no cabeçalho HTTP como: Authorization: Bearer tts-.... O prefixo tts- identifica seu token específico da Edição Voz nas requisições à API.
Endpoint Principal de Síntese
O núcleo da API é o endpoint POST /v1/audio/speech. Ele recebe texto e retorna o arquivo de áudio sintetizado, seguindo o formato padrão da indústria para simplificar a integração.
O corpo da requisição deve ser JSON. Cada solicitação processa até 4096 caracteres. Para textos maiores, divida o manuscrito e junte os arquivos resultantes.
Método POST /v1/audio/speech
Envie uma requisição POST para https://api.kohkae789.cc/v1/audio/speech. O servidor processa a síntese e retorna o arquivo de áudio diretamente na resposta.
As requisições são processadas em sequência. Em picos de uso, pode haver espera na fila.
Estrutura do JSON
O corpo da requisição deve conter os campos obrigatórios para definir o modelo, o texto a ser falado e a voz desejada.
O campo input aceita strings de texto simples, sem marcação especial.
model: "tts-1" ou "tts-1-hd"input: texto (máx. 4096 caracteres)voice: identificador da vozresponse_format: mp3, wav, opus, flac, pcmspeed: 0.25–4.0 (opcional)language: código ISO (opcional)
Parâmetros obrigatórios
Os campos model, input e voice são essenciais para a geração do áudio. O formato de resposta pode ser ajustado conforme a necessidade de qualidade ou tamanho de arquivo.
O campo speed permite alterar a velocidade da fala, enquanto language força o idioma se a detecção automática não for precisa.
Modelos de Voz Disponíveis
O endpoint suporta dois modelos de motor de síntese com o mesmo preço: tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de síntese e têm o mesmo preço.
O preço é uniforme para ambos os modelos: US$ 10 por 1 milhão de caracteres. Não há custo adicional para usar tts-1-hd, garantindo que o orçamento de produção de áudio permaneça previsível e econômico, independente da complexidade da voz selecionada.
tts-1 e tts-1-hd
Os modelos tts-1 e tts-1-hd são intercambiáveis na API. A diferença reside apenas na identificação do modelo na requisição.
Mism de preço e qualidade
A cobrança é baseada exclusivamente no volume de caracteres processados, não na complexidade do modelo. Cada caractere, incluindo espaços e pontuação, conta para o limite de 4096 caracteres por solicitação, mantendo o custo fixo em $0,01 por mil caracteres.
Seleção de voz específica
Escolha entre oito vozes pré-definidas, cada uma otimizada para diferentes tons editoriais. De aria para narrativas claras a atlas para notícias neutras, a seleção é feita via campo voice na requisição. Todas as vozes suportam os 23 idiomas listados.
Para garantir a pronúncia correta em textos latinos não ingleses, defina explicitamente o parâmetro language. Caso contrário, o sistema assume inglês para scripts latinos, o que pode afetar a naturalidade de textos em português ou espanhol.
- Vozes femininas: aria, nova, luna, sage
- Vozes masculinas: felix, milo, atlas, orion
- Suporte a 23 idiomas específicos
- Água-marcas inaudíveis em todos os arquivos
Formatos de Áudio Suportados
A API aceita MP3, WAV, Opus, FLAC e PCM via parâmetro response_format. A escolha do formato afeta apenas o arquivo final, pois o motor de síntese é idêntico para todos.
Para uso web, o MP3 é amplamente compatível. Para produção editorial, WAV ou FLAC preservam a integridade da gravação sem perdas adicionais.
MP3 para web
O formato MP3 é ideal para players de áudio online e plataformas de distribuição automática. Ele garante compatibilidade universal em navegadores e dispositivos móveis, com tamanho de arquivo reduzido.
- Compatível com a maioria dos players web
- Tamanho de arquivo otimizado
WAV para alta fidelidade
O WAV é a escolha padrão para arquivos de áudio sem compressão lossy. Ideal para quem precisa editar o áudio posteriormente em softwares profissionais ou para arquivamento master.
- Qualidade sem perda de dados
- Ampla compatência com editores de áudio
FLAC e Opus para arquivamento
O FLAC oferece compressão sem perda, reduzindo o tamanho do arquivo enquanto mantém a qualidade original. O Opus é eficiente para transmissão.
- Compressão eficiente com qualidade intacta
- Ideal para arquivamento de longo prazo
Controle de Velocidade e Idioma
O parâmetro speed permite ajustar a velocidade da fala de 0.25 a 4.0. Valores padrão mantêm um ritmo natural, ideal para audiolivros, enquanto ajustes mais altos aceleram a narração para conteúdos rápidos.
Intervalo de 0.25 a 4.0
Ajuste fino da velocidade garante que a narração se encaixe no tempo de produção desejado. Textos longos podem ser acelerados para reduzir custos de caracteres por minuto, sem perder a clareza da síntese.
Definição explícita de idioma
Para textos em idiomas não-ingleses com script latino (como português ou francês), defina o campo language explicitamente. Isso evita que a IA interprete erroneamente a pronúncia, garantindo a pronúncia correta de nomes próprios e termos técnicos.
Detecção automática de script
Se o campo language for omitido, o sistema detecta automaticamente o script (ex: cirílico, árabe). Para textos latinos não-ingleses, a detecção padrão assume inglês, tornando a definição manual essencial para autores que publicam em múltiplos idiomas.

Limites e Rate Limiting
O limite padrão é de 60 requisições por minuto por chave de API, processadas sequencialmente. Para textos longos, o ideal é dividir o manuscrito em partes de até 4096 caracteres e concatenar os arquivos de áudio resultantes.
60 requisições por minuto
As requisições são processadas uma após a outra. Em momentos de alta demanda, uma solicitação pode aguardar na fila antes da síntese iniciar. O tempo médio de geração é de cerca de 25 caracteres por segundo para textos longos.
Limite inicial reduzido
Novas contas começam com um limite mais restrito de 10 requisições por minuto. Isso se aplica até que haja o primeiro top-up na conta.
Aumento após top-up
Após a primeira recarga mínima de US$ 5 via USDT (TRC-20), o limite padrão de 60 requisições por minuto é ativado automaticamente.
Exemplo de Código cURL
A validação rápida da integração começa com um comando cURL direto para o endpoint de síntese. Este teste confirma que sua chave API está ativa e que o formato JSON está sendo processado corretamente pelo servidor.
Execute o comando abaixo substituindo sua chave real. O parâmetro output redireciona a resposta binária para um arquivo local, permitindo auditoria imediata do áudio gerado sem necessidade de scripts complexos.
Comando básico de teste
O comando cURL enviado para https://api.kohkae789.cc/v1/audio/speech deve conter o cabeçalho de autenticação Bearer e o corpo JSON com o modelo, texto e voz.
Certifique-se de que o texto esteja dentro do limite de 4096 caracteres. Qualquer erro resultará em resposta JSON de erro, mantendo o crédito intacto se a síntese falhar.
- Use
curl -X POSTpara enviar requisições. - Inclua
Authorization: Bearer SUA_CHAVE_APIno header. - Defina
Content-Type: application/json.
Parâmetros de voz
O campo voice aceita apenas os oito presets disponíveis, como 'nova' para narração clara ou 'atlas' para tom neutro. A linguagem é detectada automaticamente, mas pode ser forçada via campo language.
Não há suporte para SSML ou pronúncia customizada. O motor trata a entrada de texto padrão diretamente, garantindo consistência entre testes e produção.
Salvamento do arquivo de saída
O redirecionador > audio.mp3 captura a resposta binária diretamente. Para formatos como WAV ou FLAC, altere a extensão do arquivo de saída correspondente.
Verifique o tamanho do arquivo gerado. Se o conteúdo estiver vazio ou corrompido, revise a sintaxe do JSON ou o status da sua chave API.
Integração com SDK OpenAI
A API de texto para voz segue o mesmo formato de solicitação do endpoint de fala da OpenAI. Isso permite que você utilize os SDKs oficiais da OpenAI, apenas ajustando a configuração da URL base.
Ao modificar o base_url para https://api.kohkae789.cc/v1, os clientes OpenAI passam a enviar requisições diretamente para nosso endpoint de síntese, mantendo a estrutura JSON e o fluxo de trabalho já conhecidos pelos desenvolvedores.
Alteração do base_url ['Para integrar o SDK, basta apontar a variável de ambiente ou configuração do cliente para o domínio da API. O endpoint permanece /v1/audio/speech, garantindo compatibilidade imediata com as bibliotecas oficiais.', {'h3': 'Compatibilidade de clientes', 'paras': ['Qualquer cliente que suporte o formato JSON padrão da OpenAI funciona corretamente. A autenticação via token Bearer segue o mesmo padrão, facilitando a migração de projetos existentes.', {'h3': 'Exemplo em Python', 'paras': ['Utilize o SDK openai padrão, alterando apenas a URL base. O código envia o texto e recebe o arquivo de áudio sintetizado, pronto para ser processado ou armazenado pelo seu sistema de autoedição.', '```python\nimport openai\nclient = openai.OpenAI(\n base_url="https://api.kohkae789.cc/v1",\n api_key="tits-seu-token-aqui"\n)\n```']}], 'image': 'A clean desk setup with a laptop displaying Python code syntax highlighting, next to a pair of professional headphones, symbolizing seamless developer integration for audiobook production workflows'}]
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
