Ограничения частоты запросов
Понимание ограничений частоты запросов (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@moknah.io.