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.
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
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
Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.