Moknah 문서
무료로 시작하기
API 레퍼런스

요청 한도

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 관련 질문이나 문제는 다음 주소로 문의해 주세요: api@moknah.io.