Primeiros passos
Tudo o que você precisa para fazer sua primeira solicitação de API
URLs base
A Moknah oferece dois tipos de endpoints dependendo do seu caso de uso:
API REST padrão (para requisições únicas):
https://moknah.io/api/v1/
API WebSocket em tempo real (para streaming contínuo):
wss://moknah.io/api/v1/
Autenticação
A API da Moknah usa chaves de API para autenticação. Inclua sua chave de API no cabeçalho Authorization usando o esquema
Bearer em cada requisição HTTP e handshake WebSocket.
Authorization: Bearer YOUR_API_KEY
Como obter sua chave de API
- Faça login na sua Painel da Moknah
- Assine o Plano Pro ou fale com Vendas para acesso corporativo.
- Acesse API
- Clique em Gerenciar chaves de API
- Clique em Nova chave
- Copie e guarde sua chave com segurança
Nunca exponha sua chave de API no código do lado do cliente ou em repositórios públicos. Trate-a como uma senha.
Exemplo rápido de HTTP
Aqui está um exemplo completo para gerar fala a partir de texto usando a API REST padrão:
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1
}' \
--output speech.mp3
import requests
response = requests.post(
"https://moknah.io/api/v1/tts/generate/",
headers={
"Authorization": f"Bearer your_api_key",
},
json={
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1
}
)
if response.status_code == 200:
with open("speech.mp3", "wb") as f:
f.write(response.content)
print("Áudio salvo!")
else:
print(f"Erro: {response.json()}")
const response = await fetch(
'https://moknah.io/api/v1/tts/generate/',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'مرحبا بك في منصة مكنة',
voice_id: 1
})
}
);
if (response.ok) {
const blob = await response.blob();
// Usar o blob de áudio
console.log("Áudio gerado!");
} else {
const error = await response.json();
console.error(error);
}
Formato da resposta
Respostas de sucesso
As respostas de sucesso variam por endpoint:
- Geração TTS (POST): Retorna os dados de áudio binários completos no output_format solicitado (audio/mpeg por padrão)
- Streaming TTS (WSS): Transmite fragmentos MP3 binários continuamente à medida que são gerados
- Outros endpoints: Retorna dados JSON estruturados
Cabeçalhos de limite de taxa (apenas HTTP)
Toda resposta HTTP inclui informações de limite de taxa (WebSockets aplicam limites encerrando a conexão):
| Cabeçalho | Descrição |
|---|---|
| RateLimit-Limit | Máximo de requisições por minuto |
| RateLimit-Remaining | Requisições restantes na janela atual |
| RateLimit-Reset | Timestamp Unix de quando o limite é redefinido |
| Moknah-Credits-Remaining | Seu saldo restante de créditos |
Códigos de erro comuns
| Código | Tipo | Descrição |
|---|---|---|
| 400 | INVALID_REQUEST |
Parâmetros inválidos ou JSON malformado |
| 401 | UNAUTHORIZED |
Chave de API inválida ou ausente |
| 402 | INSUFFICIENT_CREDITS |
A conta não tem créditos suficientes |
| 429 | RATE_LIMIT_EXCEEDED |
Muitas requisições (HTTP) |
| 4290 | CONCURRENT_LIMIT |
Muitas conexões ativas (WSS) |
| 500 | INTERNAL_SERVER_ERROR |
Erro no servidor |
Consulte a página Erros para obter orientações detalhadas sobre tratamento de erros.
Próximos passos
Agora que está tudo pronto, explore os endpoints disponíveis:
Obter vozes disponíveis para TTS
Converter texto em áudio
TTS em tempo real via WebSocket
Extrair texto de arquivo de áudio
STT em tempo real via WebSocket
Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.