Moknah Документы
Начать бесплатно
Справочник по API

Ограничения частоты запросов

Понимание ограничений частоты запросов (rate limits) и конкурентности API, а также принципов работы в их рамках

Обзор

Ограничения частоты запросов защищают API от злоупотреблений и обеспечивают справедливые условия использования для всех пользователей. Moknah устанавливает лимиты на частоту запросов, расход кредитов и количество одновременных соединений как для HTTP-, так и для WebSocket-эндпоинтов.

Строгая политика запрета одновременного выполнения

Moknah выполняет точную обработку одно действие на пользователя за раз.
• HTTP: Дождитесь завершения текущего запроса, прежде чем отправлять следующий. При одновременных запросах возвращаются коды 409 Conflict или 429 Too Many Requests.
• WebSocket: Одновременно может быть открыто только одно активное WebSocket-соединение. Попытка открыть второе соединение приведет к его немедленному закрытию с кодом 4290.

Лимиты по умолчанию

Тип лимита Ценность Применимо к Описание
Запросов в минуту (RPM) 60 Только HTTP Максимальное количество стандартных POST-запросов к API в минуту.
Кредитов в минуту (CPM) 10,000 HTTP и WebSocket Максимальное количество кредитов, расходуемых в минуту.
Активные соединения 1 Только WebSocket Максимальное количество одновременных потоков WSS на пользователя.

Ограничения и коды закрытия WebSocket

Поскольку WebSockets поддерживают постоянное соединение, они не используют HTTP-заголовки для ограничения частоты запросов. Вместо этого ограничения реализуются путем разрыва соединения и использования управляющих сообщений в формате JSON:

Лимит достигнут Поведение / Выходные данные
Ограничение параллелизма Соединение мгновенно закрывается с кодом 4290.
Кредиты исчерпаны Получает ошибку JSON и закрывается.
Ограничение размера фрагмента Возникает ошибка JSON, если отдельный фрагмент текста превышает 2000 символов.
Ограничение частоты отправки сообщений Возникает JSON-ошибка, если отправлять фрагменты текста быстрее, чем очередь успевает их обрабатывать.

Примечание: Если соединение WebSocket неожиданно прервется, подождите не менее 15 секунд перед повторным подключением, чтобы убедиться, что блокировка на стороне сервера полностью снята.

HTTP-заголовки ограничения частоты запросов

Для стандартных REST-эндпоинтов каждый ответ API содержит заголовки, помогающие отслеживать статус:

Заголовок Описание Пример
RateLimit-Limit Ваш предел оборотов 60
RateLimit-Remaining Оставшиеся запросы на текущую минуту 45
RateLimit-Reset Unix-метка времени сброса лимитов 1699574460
Moknah-Credits-Remaining На данный момент остались кредиты 10000
Moknah-Credits-Used Кредиты, использованные за эту минуту 5000

При ограничении частоты HTTP-запросов

Если вы превысите лимит запросов HTTP, то получите ответ 429 Too Many Requests со следующими дополнительными заголовками:

Заголовок Описание Пример
Retry-After Время ожидания перед повторной попыткой (в секундах) 45
RateLimit-Reset Unix-метка времени, когда можно повторить попытку 1699574460

Расчет кредита

Расчет кредитов производится на основе длины текста и параметров обработки. При использовании WebSockets кредиты списываются динамически — за каждый фрагмент данных по мере их передачи.

Фактор Мультипликатор Описание
Базовая стоимость 1x 1 кредита за символ
Нормализация с использованием ИИ 2x Продвинутая обработка арабского текста с диакритикой
Голос премиум-класса +% Дополнительный процент за голоса премиум-класса

Пример: Текст объемом 500 символов с нормализацией, улучшенной с помощью ИИ:

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

Лучшие практики

1. Используйте WebSockets для передачи больших объемов последовательных текстовых данных.

Если вы генерируете ответы ИИ в режиме диалога или обрабатываете длинные документы, не отправляйте 50 HTTP-запросов POST подряд. Вместо этого откройте одно WebSocket-соединение и передавайте фрагменты данных через это постоянное соединение. Это позволит полностью обойти ограничение в 60 HTTP-запросов в минуту (хотя лимиты по кредитам при этом сохраняются).

2. Реализовать очередь запросов (HTTP)

Поскольку Moknah не поддерживает одновременные запросы, ставьте HTTP-запросы в очередь и обрабатывайте их последовательно:

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. Реализовать очередь запросов (HTTP)

Поскольку Moknah не поддерживает одновременные запросы, ставьте HTTP-запросы в очередь и обрабатывайте их последовательно:

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. Реализуйте экспоненциальную задержку

При ограничении частоты запросов (HTTP 429) или количества соединений (WebSocket 4290) используйте экспоненциальную задержку для безопасного повтора попыток, не перегружая сервер:


Резюме

Краткий справочник

Ограничения HTTP: 60 запросов в минуту, 1 одновременный запрос.
Ограничения WebSocket: 1 одновременное соединение, 2000 символов на фрагмент.
Общие ограничения: 10 000 CPM (кредитов в минуту).
Нужна большая емкость? Электронная почта sales@moknah.io

Поддержка API

По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.