Moknah Documenti
Inizia gratis
Riferimento API

Limiti di frequenza

Comprendere i rate limit dell'API, la concorrenza e come gestirli

Panoramica

I rate limit proteggono l'API dagli abusi e garantiscono un utilizzo equo per tutti gli utenti. Moknah applica limiti sulla frequenza delle richieste, sul consumo di crediti e sulle connessioni simultanee sia sui nostri endpoint HTTP che WebSocket.

Politica rigorosa di non concorrenza

Moknah elabora esattamente un'azione per utente alla volta.
• HTTP: Attendi il completamento della richiesta in corso prima di inviarne un'altra. Le richieste simultanee ricevono un errore 409 Conflict o 429 Too Many Requests.
• WebSocket: Puoi avere solo 1 connessione WebSocket attiva alla volta. L'apertura di una seconda connessione verrà chiusa istantaneamente con il codice 4290.

Limiti predefiniti

Tipo di limite Valore Si applica a Descrizione
Richieste al minuto (RPM) 60 Solo HTTP Numero massimo di richieste POST API standard al minuto.
Crediti al minuto (CPM) 10,000 HTTP e WebSocket Crediti massimi consumati al minuto.
Connessioni attive 1 Solo WebSocket Numero massimo di flussi WSS simultanei per utente.

Limiti e codici di chiusura WebSocket

Poiché i WebSocket mantengono una connessione persistente, non usano header HTTP per il rate limiting. I limiti vengono invece applicati tramite disconnessioni e messaggi di controllo JSON:

Limite raggiunto Comportamento / Output
Limite di concorrenza La connessione si chiude istantaneamente con il codice 4290.
Crediti esauriti Riceve un errore JSON e si chiude.
Limite dimensione frammento Riceve un errore JSON se un singolo frammento di testo supera i 2.000 caratteri.
Limite di frequenza dei messaggi Riceve un errore JSON se invii frammenti di testo più velocemente di quanto la coda possa elaborarli.

Nota: se il WebSocket si disconnette in modo imprevisto, attendi almeno 15 secondi prima di riconnetterti per assicurarti che il blocco lato server sia stato completamente rimosso.

Header HTTP di rate limit

Per gli endpoint REST standard, ogni risposta dell'API include header che ti aiutano a monitorare il tuo stato:

Header Descrizione Esempio
RateLimit-Limit Il tuo limite di richieste al minuto (RPM) 60
RateLimit-Remaining Richieste rimanenti in questo minuto 45
RateLimit-Reset Timestamp Unix di ripristino dei limiti 1699574460
Moknah-Credits-Remaining Crediti rimanenti in questo minuto 10000
Moknah-Credits-Used Crediti utilizzati in questo minuto 5000

Al raggiungimento del rate limit HTTP

Se superi il rate limit HTTP, riceverai una risposta 429 Too Many Requests con questi header aggiuntivi:

Header Descrizione Esempio
Retry-After Secondi da attendere prima di riprovare 45
RateLimit-Reset Timestamp Unix a partire dal quale puoi riprovare 1699574460

Calcolo dei crediti

I crediti vengono calcolati in base alla lunghezza del testo e alle opzioni di elaborazione. Per i WebSocket, i crediti vengono detratti dinamicamente per ciascun frammento durante lo streaming.

Fattore Moltiplicatore Descrizione
Costo base 1x 1 crediti per carattere
Normalizzazione potenziata dall'IA 2x Elaborazione avanzata dell'arabo con segni diacritici
Voce Premium +% Percentuale aggiuntiva per le voci premium

Esempio: Un testo di 500 caratteri con normalizzazione potenziata dall'IA:

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

Best practice

1. Usa WebSocket per testi sequenziali ad alto volume

Se stai generando risposte di IA conversazionale o analizzando documenti lunghi, non inviare 50 richieste HTTP POST ravvicinate. Apri una singola connessione WebSocket e trasmetti i frammenti in streaming sulla connessione persistente. Questo aggira completamente il limite HTTP di 60 RPM (anche se i limiti di crediti restano validi).

2. Implementa una coda di richieste (HTTP)

Poiché Moknah non supporta richieste simultanee, metti in coda le tue richieste HTTP ed elaborale in modo sequenziale:

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 coda di richieste (HTTP)

Poiché Moknah non supporta richieste simultanee, metti in coda le tue richieste HTTP ed elaborale in modo sequenziale:

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 il backoff esponenziale

Quando raggiungi il limite di frequenza (HTTP 429) o di connessione (WebSocket 4290), usa il backoff esponenziale per riprovare in sicurezza senza sovraccaricare il server:


Riepilogo

Riferimento rapido

Limiti HTTP: 60 RPM, 1 richiesta simultanea.
Limiti WebSocket: 1 connessione simultanea, 2.000 caratteri per frammento.
Limiti globali: 10.000 CPM (crediti al minuto).
Hai bisogno di più capacità? Email sales@moknah.io

Supporto API

Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.