Moknah Documentação
Comece grátis
Referência da API

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.

Política estrita de não simultaneidade

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

Referência rápida

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

Suporte da API

Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.