Moknah Dokumentacja
Zacznij za darmo
Dokumentacja API

Limity zapytań

Zrozumienie limitów zapytań API, współbieżności oraz sposobu pracy w ich ramach

Przegląd

Limity zapytań chronią API przed nadużyciami i zapewniają uczciwe korzystanie dla wszystkich użytkowników. Moknah egzekwuje limity częstotliwości zapytań, zużycia kredytów oraz jednoczesnych połączeń zarówno dla punktów końcowych HTTP, jak i WebSocket.

Ścisła polityka braku współbieżności

Moknah przetwarza dokładnie jedną akcję na użytkownika naraz.
• HTTP: Poczekaj na zakończenie bieżącego zapytania przed wysłaniem kolejnego. Jednoczesne zapytania otrzymają błąd 409 Conflict lub 429 Too Many Requests.
• WebSocket: Możesz mieć tylko 1 aktywne połączenie WebSocket naraz. Otwarcie drugiego połączenia spowoduje jego natychmiastowe zamknięcie z kodem 4290.

Domyślne limity

Typ limitu Wartość Dotyczy Opis
Zapytania na minutę (RPM) 60 Tylko HTTP Maksymalna liczba standardowych zapytań API POST na minutę.
Kredyty na minutę (CPM) 10,000 HTTP i WebSocket Maksymalna liczba kredytów zużywanych na minutę.
Aktywne połączenia 1 Tylko WebSocket Maksymalna liczba jednoczesnych strumieni WSS na użytkownika.

Limity i kody zamknięcia WebSocket

Ponieważ połączenia WebSocket są trwałe, nie używają nagłówków HTTP do ograniczania liczby zapytań. Zamiast tego limity są egzekwowane poprzez zrywanie połączeń i komunikaty sterujące JSON:

Osiągnięty limit Zachowanie / Wynik
Limit współbieżności Połączenie zostaje natychmiast zamknięte z kodem 4290.
Wyczerpane kredyty Otrzymuje błąd JSON i zamyka połączenie.
Limit rozmiaru fragmentu Otrzymuje błąd JSON, jeśli pojedynczy fragment tekstu przekracza 2000 znaków.
Limit częstotliwości wiadomości Otrzymuje błąd JSON, jeśli wysyłasz fragmenty tekstu szybciej, niż kolejka jest w stanie je przetwarzać.

Uwaga: jeśli połączenie WebSocket zostanie nieoczekiwanie przerwane, odczekaj co najmniej 15 sekund przed ponownym połączeniem, aby upewnić się, że blokada po stronie serwera została całkowicie zwolniona.

Nagłówki limitów zapytań HTTP

W przypadku standardowych punktów końcowych REST każda odpowiedź API zawiera nagłówki ułatwiające monitorowanie statusu:

Nagłówek Opis Przykład
RateLimit-Limit Twój limit zapytań na minutę (RPM) 60
RateLimit-Remaining Pozostałe zapytania w tej minucie 45
RateLimit-Reset Znacznik czasu Unix resetowania limitów 1699574460
Moknah-Credits-Remaining Pozostałe kredyty w tej minucie 10000
Moknah-Credits-Used Wykorzystane kredyty w tej minucie 5000

Po przekroczeniu limitu zapytań HTTP

Jeśli przekroczysz limit zapytań HTTP, otrzymasz odpowiedź 429 Too Many Requests z następującymi dodatkowymi nagłówkami:

Nagłówek Opis Przykład
Retry-After Liczba sekund oczekiwania przed ponowną próbą 45
RateLimit-Reset Znacznik czasu Unix możliwego ponowienia próby 1699574460

Obliczanie kredytów

Kredyty są obliczane na podstawie długości tekstu i opcji przetwarzania. W przypadku WebSocket kredyty są pobierane dynamicznie za każdy fragment podczas strumieniowania.

Czynnik Mnożnik Opis
Koszt podstawowy 1x 1 kredytów za znak
Normalizacja wspomagana przez AI 2x Zaawansowane przetwarzanie języka arabskiego ze znakami diakrytycznymi
Głos Premium +% Dodatkowy procent dla głosów premium

Przykład: Tekst o długości 500 znaków z normalizacją wspomaganą przez AI:

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

Najlepsze praktyki

1. Używaj WebSockets do dużych ilości tekstu sekwencyjnego

Jeśli generujesz odpowiedzi konwersacyjnej AI lub przetwarzasz długie dokumenty, nie wysyłaj 50 szybkich żądań HTTP POST. Otwórz jedno połączenie WebSocket i przesyłaj fragmenty strumieniowo przez trwałe połączenie. Pozwala to całkowicie ominąć limit HTTP wynoszący 60 RPM (choć limity kredytów nadal obowiązują).

2. Wdróż kolejkowanie żądań (HTTP)

Ponieważ Moknah nie obsługuje jednoczesnych żądań, umieszczaj żądania HTTP w kolejce i przetwarzaj je sekwencyjnie:

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. Wdróż kolejkowanie żądań (HTTP)

Ponieważ Moknah nie obsługuje jednoczesnych żądań, umieszczaj żądania HTTP w kolejce i przetwarzaj je sekwencyjnie:

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. Wdróż wykładnicze opóźnianie ponowień (Exponential Backoff)

W przypadku przekroczenia limitu zapytań (HTTP 429) lub limitu połączeń (WebSocket 4290) użyj wykładniczego opóźniania ponowień, aby bezpiecznie ponowić próbę bez przeciążania serwera:


Podsumowanie

Szybkie podsumowanie

Limity HTTP: 60 RPM, 1 jednoczesne żądanie.
Limity WebSocket: 1 jednoczesne połączenie, 2000 znaków na fragment.
Limity globalne: 10 000 CPM (kredytów na minutę).
Potrzebujesz większej przepustowości? E-mail sales@moknah.io

Wsparcie API

W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.