요청 한도
API 속도 제한 및 동시성 이해와 활용 방법
개요
속도 제한은 남용으로부터 API를 보호하고 모든 사용자에게 공정한 사용을 보장합니다. Moknah는 HTTP 및 WebSocket 엔드포인트 모두에서 요청 빈도, 크레딧 소모량 및 동시 연결 수를 제한합니다.
Moknah는 정확히 사용자당 한 번에 하나의 작업만 처리합니다.
• HTTP: 다른 요청을 보내기 전에 현재 요청이 완료될 때까지 기다려 주세요. 동시 요청 시 409 Conflict 또는 429 Too Many Requests 오류가 반환됩니다.
• WebSocket: 한 번에 1개의 활성 WebSocket 연결만 열 수 있습니다. 두 번째 연결을 열면 코드 4290과 함께 즉시 종료됩니다.
기본 제한
| 제한 유형 | 값 | 적용 대상 | 설명 |
|---|---|---|---|
| 분당 요청 수 (RPM) | 60 |
HTTP 전용 | 분당 표준 API POST 요청의 최대 횟수입니다. |
| 분당 크레딧 (CPM) | 10,000 |
HTTP 및 WebSocket | 분당 최대 소모 크레딧 수입니다. |
| 활성 연결 | 1 |
WebSocket 전용 | 사용자당 최대 동시 WSS 스트림 수입니다. |
WebSocket 한도 및 종료 코드
WebSocket은 지속적인 연결을 유지하므로 요청 제한에 HTTP 헤더를 사용하지 않습니다. 대신 연결 종료 및 JSON 제어 메시지를 통해 제한이 적용됩니다.
| 도달한 한도 | 동작 / 출력 |
|---|---|
| 동시 연결 한도 | 코드 4290과 함께 연결이 즉시 종료됩니다. |
| 크레딧 소진 | JSON 오류를 수신하고 연결이 종료됩니다. |
| 청크 크기 한도 | 단일 텍스트 청크가 2,000자를 초과하면 JSON 오류를 수신합니다. |
| 메시지 전송률 한도 | 대기열에서 처리할 수 있는 속도보다 빠르게 텍스트 청크를 보내면 JSON 오류를 수신합니다. |
참고: WebSocket 연결이 예기치 않게 끊어진 경우 서버 측 잠금이 완전히 해제되도록 최소 15초 동안 기다린 후 다시 연결하세요.
HTTP 요청 제한 헤더
표준 REST 엔드포인트의 경우 모든 API 응답에 상태를 파악하는 데 도움이 되는 헤더가 포함됩니다.
| 헤더 | 설명 | 예시 |
|---|---|---|
RateLimit-Limit |
분당 요청 수(RPM) 한도 | 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 |
크레딧 계산
크레딧은 텍스트 길이와 처리 옵션에 따라 계산됩니다. WebSocket의 경우 스트리밍되는 청크 단위로 크레딧이 동적으로 차감됩니다.
| 요소 | 배수 | 설명 |
|---|---|---|
| 기본 비용 | 1x |
글자당 1 크레딧 |
| AI 향상 정규화 | 2x |
발음 구별 부호를 포함한 고급 아랍어 처리 |
| 프리미엄 보이스 | +% |
프리미엄 보이스에 대한 추가 비율 |
예시: AI 향상 정규화가 적용된 500자 텍스트:
500 characters × 2 (AI-Enhanced) = 1,000 credits
모범 사례
1. 대용량 순차 텍스트에는 WebSocket 사용
대화형 AI 응답을 생성하거나 긴 문서를 파싱하는 경우 50개의 빠른 HTTP POST 요청을 보내지 마세요. 단일 WebSocket 연결을 열고 지속 연결을 통해 청크를 스트리밍하세요. 이렇게 하면 60 RPM의 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 RPM, 동시 요청 1개.
WebSocket 한도: 동시 연결 1개, 청크당 2,000자.
전역 한도: 10,000 CPM (분당 크레딧).
더 많은 용량이 필요하신가요? 이메일 sales@moknah.io
API 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.