حدود الاستخدام

فهم حدود استخدام واجهة برمجة التطبيقات، التزامن، وكيفية العمل ضمنها

نظرة عامة

تحمي حدود الاستخدام واجهة برمجة التطبيقات من سوء الاستخدام وتضمن الاستخدام العادل لجميع المستخدمين. تفرض مكنه حدوداً على تكرار الطلبات، واستهلاك الرصيد، والاتصالات المتزامنة عبر كل من نقاط نهاية HTTP وWebSocket.

الحدود الافتراضية

حدود WebSocket وأكواد الإغلاق

بما أن WebSockets تحافظ على اتصال دائم، فهي لا تستخدم ترويسات HTTP لتحديد الاستخدام. بدلاً من ذلك، يتم فرض الحدود عبر قطع الاتصال ورسائل تحكم JSON:

ملاحظة: إذا انقطع اتصال WebSocket بشكل غير متوقع، انتظر 15 ثانية على الأقل قبل إعادة الاتصال للتأكد من فك القفل من جانب الخادم تماماً.

ترويسات حدود استخدام HTTP

بالنسبة لنقاط نهاية REST القياسية، تتضمن كل استجابة API ترويسات لمساعدتك في تتبع حالتك:

عند تجاوز حد استخدام HTTP

إذا تجاوزت حد استخدام HTTP، فستتلقى استجابة 429 Too Many Requests مع هذه الترويسات الإضافية:

حساب النقاط

يتم حساب النقاط بناءً على طول النص وخيارات المعالجة. بالنسبة لـ WebSockets، يتم خصم النقاط ديناميكياً لكل مقطع أثناء البث.

مثال: نص مكون من 500 حرف مع المعالجة المحسنة بالذكاء الاصطناعي:

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

أفضل الممارسات

1. استخدم WebSockets للنصوص المتسلسلة ذات الحجم الكبير

إذا كنت تقوم بتوليد ردود ذكاء اصطناعي محادثاتية أو تحليل مستندات طويلة، فلا تقم بإجراء 50 طلب HTTP POST سريع. افتح اتصال WebSocket واحداً وبث المقاطع عبر الاتصال الدائم. هذا يتجاوز حد 60 طلب في الدقيقة لـ HTTP تماماً (على الرغم من استمرار تطبيق حدود النقاط).

2. تنفيذ صف الطلبات (HTTP)

بما أن مكنه لا تدعم الطلبات المتزامنة، قم بوضع طلبات 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)

بما أن مكنه لا تدعم الطلبات المتزامنة، قم بوضع طلبات 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)، استخدم التراجع الأسي لإعادة المحاولة بأمان دون إغراق الخادم بالطلبات.

ملخص