Moknah Documentación
Empieza gratis
Referencia de la API

Límites de uso

Comprende los límites de tasa de la API, la concurrencia y cómo trabajar con ellos

Resumen

Los límites de tasa protegen la API contra abusos y garantizan un uso justo para todos los usuarios. Moknah aplica límites en la frecuencia de solicitudes, el consumo de créditos y las conexiones simultáneas tanto en nuestros endpoints HTTP como WebSocket.

Política estricta de no concurrencia

Moknah procesa exactamente una acción por usuario a la vez.
• HTTP: Espera a que se complete la solicitud actual antes de enviar otra. Las solicitudes simultáneas reciben un error 409 Conflict o 429 Too Many Requests.
• WebSocket: Solo puedes tener 1 conexión WebSocket activa a la vez. Si abres una segunda conexión, se cerrará al instante con el código 4290.

Límites predeterminados

Tipo de límite Valor Se aplica a Descripción
Solicitudes por minuto (RPM) 60 Solo HTTP Número máximo de solicitudes POST estándar de la API por minuto.
Créditos por minuto (CPM) 10,000 HTTP y WebSocket Máximo de créditos consumidos por minuto.
Conexiones activas 1 Solo WebSocket Número máximo de transmisiones WSS simultáneas por usuario.

Límites y códigos de cierre de WebSocket

Dado que los WebSockets mantienen una conexión persistente, no usan encabezados HTTP para limitar las solicitudes. En su lugar, los límites se aplican mediante cierres de conexión y mensajes de control JSON:

Límite alcanzado Comportamiento / Salida
Límite de concurrencia La conexión se cierra al instante con el código 4290.
Créditos agotados Recibe un error JSON y se cierra.
Límite de tamaño de fragmento Recibe un error JSON si un solo fragmento de texto supera los 2,000 caracteres.
Límite de frecuencia de mensajes Recibe un error JSON si envías fragmentos de texto más rápido de lo que la cola puede procesarlos.

Nota: Si tu WebSocket se desconecta inesperadamente, espera al menos 15 segundos antes de reconectar para asegurarte de que el bloqueo del servidor se haya liberado por completo.

Encabezados HTTP de límite de solicitudes

Para los endpoints REST estándar, cada respuesta de la API incluye encabezados que te ayudan a monitorear tu estado:

Encabezado Descripción Ejemplo
RateLimit-Limit Tu límite de solicitudes por minuto (RPM) 60
RateLimit-Remaining Solicitudes restantes en este minuto 45
RateLimit-Reset Marca de tiempo Unix cuando se restablecen los límites 1699574460
Moknah-Credits-Remaining Créditos restantes en este minuto 10000
Moknah-Credits-Used Créditos usados en este minuto 5000

Cuando se alcanza el límite de solicitudes HTTP

Si superas el límite de solicitudes HTTP, recibirás una respuesta 429 Too Many Requests con estos encabezados adicionales:

Encabezado Descripción Ejemplo
Retry-After Segundos de espera antes de reintentar 45
RateLimit-Reset Marca de tiempo Unix cuando puedes reintentar 1699574460

Cálculo de créditos

Los créditos se calculan según la longitud del texto y las opciones de procesamiento. Para WebSockets, los créditos se descuentan dinámicamente por fragmento a medida que se transmiten.

Factor Multiplicador Descripción
Costo base 1x 1 créditos por carácter
Normalización mejorada con IA 2x Procesamiento avanzado de árabe con signos diacríticos
Voz Premium +% Porcentaje adicional para voces premium

Ejemplo: Un texto de 500 caracteres con normalización mejorada por IA:

500 characters × 2 (AI-Enhanced) = 1,000 credits

Mejores prácticas

1. Usa WebSockets para texto secuencial de gran volumen

Si estás generando respuestas de IA conversacional o procesando documentos largos, no hagas 50 solicitudes HTTP POST rápidas. Abre una única conexión WebSocket y transmite los fragmentos a través de la conexión persistente. Esto evita por completo el límite HTTP de 60 RPM (aunque los límites de créditos siguen aplicando).

2. Implementa una cola de solicitudes (HTTP)

Como Moknah no admite solicitudes simultáneas, pon tus solicitudes HTTP en cola y procésalas de forma secuencial:

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. Implementa una cola de solicitudes (HTTP)

Como Moknah no admite solicitudes simultáneas, pon tus solicitudes HTTP en cola y procésalas de forma secuencial:

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. Implementa el retroceso exponencial

Cuando alcances el límite de tasa (HTTP 429) o el límite de conexiones (WebSocket 4290), usa retroceso exponencial para reintentar de forma segura sin saturar el servidor:


Resumen

Referencia rápida

Límites de HTTP: 60 RPM, 1 solicitud simultánea.
Límites de WebSocket: 1 conexión simultánea, 2,000 caracteres por fragmento.
Límites globales: 10,000 CPM (créditos por minuto).
¿Necesitas más capacidad? Correo electrónico sales@moknah.io

Soporte de API

Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.