Limites de taxa
Entenda os limites de taxa da API, simultaneidade e como trabalhar dentro deles
Visão geral
Os limites de taxa protegem a API contra abusos e garantem o uso justo para todos os usuários. A Moknah aplica limites na frequência de requisições, consumo de créditos e conexões simultâneas em nossos endpoints HTTP e WebSocket.
A Moknah processa exatamente uma ação por usuário por vez.
• HTTP: Aguarde a conclusão da requisição atual antes de enviar outra. Requisições simultâneas recebem um erro 409 Conflict ou 429 Too Many Requests.
• WebSocket: Você só pode ter 1 conexão WebSocket ativa por vez. Abrir uma segunda conexão fará com que ela seja encerrada instantaneamente com o código 4290.
Limites padrão
| Tipo de limite | Valor | Aplica-se a | Descrição |
|---|---|---|---|
| Requisições por minuto (RPM) | 60 |
Apenas HTTP | Número máximo de requisições POST padrão da API por minuto. |
| Créditos por minuto (CPM) | 10,000 |
HTTP e WebSocket | Máximo de créditos consumidos por minuto. |
| Conexões ativas | 1 |
Apenas WebSocket | Número máximo de fluxos WSS simultâneos por usuário. |
Limites e códigos de fechamento de WebSocket
Como os WebSockets mantêm uma conexão persistente, eles não usam cabeçalhos HTTP para limitação de taxa. Em vez disso, os limites são aplicados por meio de quedas de conexão e mensagens de controle JSON:
| Limite atingido | Comportamento / Saída |
|---|---|
| Limite de simultaneidade | A conexão é fechada instantaneamente com o código 4290. |
| Créditos esgotados | Recebe erro JSON e fecha. |
| Limite de tamanho de bloco | Recebe erro JSON se um único bloco de texto exceder 2.000 caracteres. |
| Limite de taxa de mensagens | Recebe erro JSON se você enviar blocos de texto mais rápido do que a fila consegue processar. |
Observação: Se o seu WebSocket desconectar inesperadamente, aguarde pelo menos 15 segundos antes de reconectar para garantir que o bloqueio no servidor tenha sido totalmente liberado.
Cabeçalhos HTTP de limite de taxa
Para endpoints REST padrão, cada resposta da API inclui cabeçalhos para ajudar você a acompanhar seu status:
| Cabeçalho | Descrição | Exemplo |
|---|---|---|
RateLimit-Limit |
Seu limite de requisições por minuto (RPM) | 60 |
RateLimit-Remaining |
Requisições restantes neste minuto | 45 |
RateLimit-Reset |
Timestamp Unix de quando os limites são redefinidos | 1699574460 |
Moknah-Credits-Remaining |
Créditos restantes neste minuto | 10000 |
Moknah-Credits-Used |
Créditos usados neste minuto | 5000 |
Quando o limite de taxa HTTP é atingido
Se você exceder o limite de taxa HTTP, receberá uma resposta 429 Too Many Requests com estes cabeçalhos adicionais:
| Cabeçalho | Descrição | Exemplo |
|---|---|---|
Retry-After |
Segundos para aguardar antes de tentar novamente | 45 |
RateLimit-Reset |
Timestamp Unix de quando você pode tentar novamente | 1699574460 |
Cálculo de créditos
Os créditos são calculados com base no tamanho do texto e nas opções de processamento. Para WebSockets, os créditos são deduzidos dinamicamente por bloco conforme são transmitidos.
| Fator | Multiplicador | Descrição |
|---|---|---|
| Custo base | 1x |
1 créditos por caractere |
| Normalização aprimorada por IA | 2x |
Processamento avançado de árabe com diacríticos |
| Voz Premium | +% |
Porcentagem adicional para vozes premium |
Exemplo: Um texto de 500 caracteres com normalização aprimorada por IA:
500 characters × 2 (AI-Enhanced) = 1,000 credits
Boas práticas
1. Use WebSockets para textos sequenciais de alto volume
Se você estiver gerando respostas de IA conversacional ou analisando documentos longos, não faça 50 requisições HTTP POST rápidas. Abra uma única conexão WebSocket e transmita os trechos pela conexão persistente. Isso ignora completamente o limite HTTP de 60 RPM (embora os limites de créditos continuem valendo).
2. Implemente fila de requisições (HTTP)
Como a Moknah não oferece suporte a requisições simultâneas, coloque suas requisições HTTP em uma fila e processe-as sequencialmente:
import queue
import threading
import time
class TTSQueue:
def __init__(self, api_key):
self.api_key = api_key
self.queue = queue.Queue()
self.worker = threading.Thread(target=self._process_queue, daemon=True)
self.worker.start()
def _process_queue(self):
while True:
text, voice_id, callback = self.queue.get()
try:
result = self._generate(text, voice_id)
callback(result, None)
except Exception as e:
callback(None, e)
finally:
self.queue.task_done()
def _generate(self, text, voice_id):
# Your API call here
pass
def add(self, text, voice_id, callback):
self.queue.put((text, voice_id, callback))
# Usage
tts = TTSQueue("your_api_key")
tts.add("Hello world", "voice_123", lambda r, e: print(r or e))
class TTSQueue {
constructor(apiKey) {
this.apiKey = apiKey;
this.queue = [];
this.processing = false;
}
async add(text, voiceId) {
return new Promise((resolve, reject) => {
this.queue.push({ text, voiceId, resolve, reject });
this.processNext();
});
}
async processNext() {
if (this.processing || this.queue.length === 0) return;
this.processing = true;
const { text, voiceId, resolve, reject } = this.queue.shift();
try {
const result = await this.generate(text, voiceId);
resolve(result);
} catch (error) {
reject(error);
} finally {
this.processing = false;
this.processNext(); // Process next in queue
}
}
async generate(text, voiceId) {
// Your API call here
}
}
// Usage
const tts = new TTSQueue("your_api_key");
const audio = await tts.add("Hello world", "voice_123");
2. Implemente fila de requisições (HTTP)
Como a Moknah não oferece suporte a requisições simultâneas, coloque suas requisições HTTP em uma fila e processe-as sequencialmente:
import time
import random
def request_with_backoff(func, max_retries=5):
retries = 0
while retries < max_retries:
try:
response = func()
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
# Add jitter to prevent thundering herd
wait_time = retry_after + random.uniform(0, 1)
print(f"Rate limited. Waiting {wait_time:.1f}s...")
time.sleep(wait_time)
retries += 1
continue
return response
except Exception as e:
# Exponential backoff for other errors
wait_time = (2 ** retries) + random.uniform(0, 1)
print(f"Error: {e}. Retrying in {wait_time:.1f}s...")
time.sleep(wait_time)
retries += 1
raise Exception("Max retries exceeded")
async function requestWithBackoff(func, maxRetries = 5) {
let retries = 0;
while (retries < maxRetries) {
try {
const response = await func();
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get("Retry-After") || 60);
// Add jitter to prevent thundering herd
const waitTime = retryAfter + Math.random();
console.log(`Rate limited. Waiting ${waitTime.toFixed(1)}s...`);
await new Promise(r => setTimeout(r, waitTime * 1000));
retries++;
continue;
}
return response;
} catch (error) {
// Exponential backoff for other errors
const waitTime = Math.pow(2, retries) + Math.random();
console.log(`Error: ${error.message}. Retrying in ${waitTime.toFixed(1)}s...`);
await new Promise(r => setTimeout(r, waitTime * 1000));
retries++;
}
}
throw new Error("Max retries exceeded");
}
3. Implemente o backoff exponencial
Ao atingir o limite de taxa (HTTP 429) ou o limite de conexão (WebSocket 4290), use o backoff exponencial para tentar novamente com segurança sem sobrecarregar o servidor:
Resumo
Limites de HTTP: 60 RPM, 1 requisição simultânea.
Limites de WebSocket: 1 conexão simultânea, 2.000 caracteres por trecho.
Limites globais: 10.000 CPM (créditos por minuto).
Precisa de mais capacidade? E-mail sales@moknah.io
Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.