محدودیت نرخ API AvalAI و سطوح حساب

این راهنما محدودیت‌های نرخ API AvalAI، سطوح حساب و نحوه دریافت تا ۲۰۰٬۰۰۰ تومان اعتبار رایگان ثبت‌نام با تأیید شمارهٔ تلفن را توضیح می‌دهد.

درک محدودیت‌های نرخ

محدودیت‌های نرخ، محدودیت‌هایی بر تعداد درخواست‌های API هستند که می‌توانید در یک دوره زمانی معین ارسال کنید. این محدودیت‌ها برای اطمینان از استفاده منصفانه از API و جلوگیری از سوء استفاده وضع شده‌اند. AvalAI محدودیت‌های نرخ را مشابه رویکرد OpenAI پیاده‌سازی می‌کند، با ارتقای خودکار سطح بر اساس استفاده شما.

درک سطوح استفاده

AvalAI از یک سیستم سطح‌بندی استفاده می‌کند که در آن محدودیت‌های نرخ شما به‌صورت خودکار رشد می‌کنند — نخست با تأیید شمارهٔ تلفن و سپس از طریق شارژ تجمعی حساب. هیچ فرم درخواستی، دورهٔ انتظار یا تأیید دستی وجود ندارد: به‌محض اینکه شرایط یک سطح را برآورده کنید، محدودیت‌های جدید بلافاصله فعال می‌شوند.

نحوه کار محدودیت‌های نرخ

محدودیت‌های نرخ به پنج روش اندازه‌گیری می‌شوند:

• RPM (درخواست در دقیقه)
• RPD (درخواست در روز)
• TPM (توکن در دقیقه)
• TPD (توکن در روز)
• IPM (تصویر در دقیقه)

شما می‌توانید به محدودیت‌های نرخ در هر یک از این معیارها برسید، بسته به اینکه کدام یک اول برسد. برای مثال، ممکن است ۲۰ درخواست با تنها ۱۰۰ توکن ارسال کنید و به محدودیت RPM خود برسید، حتی اگر به محدودیت TPM نرسیده باشید.

شرایط سطوح

هر کاربری که در AvalAI ثبت‌نام کند بلافاصله می‌تواند از API استفاده کند. سطح شما بر اساس دو عامل تعیین می‌شود:

1. روش تأیید حساب — فقط با ایمیل، یا با شمارهٔ تلفن.
2. مجموع شارژ تجمعی — شارژها در طول عمر حسابتان روی هم انباشته می‌شوند.

سطح	روش رسیدن به این سطح	اعتبار رایگان ثبت‌نام	محدودیت‌های نرخ
سطح پایه (Tier 0)	ثبت‌نام فقط با ایمیل	۲۵٬۰۰۰ تومان	محدودیت‌های نرخ سطح پایه را ببینید
سطح ۱	ثبت‌نام با تلفن یا اتصال و تأیید آن در ادامه	در مجموع ۲۰۰٬۰۰۰ تومان	محدودیت‌های نرخ سطح ۱ را ببینید
سطح ۲	مجموع شارژ معادل ۱۰ دلار	اعتبار ثبت‌نام تا زمان مصرف باقی می‌ماند	محدودیت‌های نرخ سطح ۲ را ببینید
سطح ۳	مجموع شارژ معادل ۵۰ دلار	اعتبار ثبت‌نام تا زمان مصرف باقی می‌ماند	محدودیت‌های نرخ سطح ۳ را ببینید
سطح ۴	مجموع شارژ معادل ۲۵۰ دلار	اعتبار ثبت‌نام تا زمان مصرف باقی می‌ماند	محدودیت‌های نرخ سطح ۴ را ببینید
سطح ۵	مجموع شارژ معادل ۱٬۰۰۰ دلار	اعتبار ثبت‌نام تا زمان مصرف باقی می‌ماند	محدودیت‌های نرخ سطح ۵ را ببینید

نکات کاربردی:

• 🎁 با شمارهٔ تلفن ثبت‌نام و آن را تأیید کنید تا ۲۰۰٬۰۰۰ تومان اعتبار رایگان API بگیرید. هیچ شارژی لازم نیست.
• ✉️ می‌توانید با ایمیل شروع کنید. ثبت‌نام فقط با ایمیل، بلافاصله ۲۵٬۰۰۰ تومان اعتبار رایگان در سطح پایه ارائه می‌دهد.
• 📱 بعدا تلفن را اضافه و تأیید کنید تا ۱۷۵٬۰۰۰ تومان دیگر بگیرید. با این کار مجموع اعتبار رایگان حساب ایمیلی به همان ۲۰۰٬۰۰۰ تومان می‌رسد و حساب فورا به سطح ۱ ارتقا می‌یابد. پاداش تلفن، مجموع را به ۲۰۰٬۰۰۰ تومان می‌رساند و ۲۰۰٬۰۰۰ تومان جداگانه علاوه بر اعتبار ایمیل نیست.
• ⚡ ارتقای سطح، خودکار و آنی است — به‌محض رسیدن به آستانهٔ بعدی، بدون نیاز به تیکت پشتیبانی یا انتظار، سطح شما ارتقا می‌یابد.
• 💳 شارژها تجمعی محاسبه می‌شوند. سطوح ۲ به بالا بر اساس مجموع شارژ تاریخی حساب شما تعیین می‌شوند، نه موجودی فعلی، و هیچ اعتباری بابت ارتقا کسر نمی‌شود — تمام اعتبار شما برای استفاده از API باقی می‌ماند.
• 💱 شارژها به ریال انجام می‌شوند و معادل دلاری آن برای تعیین سطح، بر اساس نرخ ارز نمایش‌داده‌شده در chat.avalai.ir/platform محاسبه می‌شود. (اعتبار تومانی به‌صورت خودکار به تتر تبدیل نمی‌شود و فقط معادل آن برای محاسبهٔ سطح دسترسی بررسی می‌گردد. در صورت تمایل می‌توانید با کسر ۳٪ کارمزد، اعتبار تومانی خود را در chat.avalai.ir/platform/billing/credit به معادل تتر تبدیل کنید.)
• 📈 هیچ سقف هزینهٔ ماهانه‌ای وجود ندارد — هر زمان نیاز داشتید می‌توانید از کل موجودی اعتبار خود استفاده کنید.
• 🤖 هر سطح دسترسی به مدل‌های بیشتر و محدودیت‌های نرخ بالاتر برای هر مدل فراهم می‌کند. محدودیت‌ها برای هر مدل و در سطح سازمان تعریف می‌شوند.

برای محدودیت‌های نرخ دقیق هر مدل در سطح خود، از صفحات مخصوص هر سطح که در بالا لینک شده‌اند دیدن کنید.

محدودیت‌های نرخ API کاربر (/user/v1)

نقاط پایانی /user/v1 دارای محدودیت‌های زیر برای تعداد درخواست هر کاربر هستند. محدودیت سطح فعلی حساب شما در همهٔ این نقاط پایانی اعمال می‌شود.

سطح حساب	محدودیت درخواست
سطح پایه (سطح ۰)	۳ درخواست در دقیقه
سطح ۱	۱۵ درخواست در دقیقه
سطح ۲	۵۰ درخواست در دقیقه
سطح ۳	۱۵۰ درخواست در دقیقه
سطح ۴	۳۵۰ درخواست در دقیقه
سطح ۵	۷۵۰ درخواست در دقیقه

برای جزئیات نقاط پایانی، مرجع API کاربر را ببینید.

هدرهای محدودیت نرخ

هنگامی که درخواست‌های API ارسال می‌کنید، هدرهای پاسخ شامل اطلاعاتی در مورد وضعیت فعلی محدودیت نرخ شما هستند:

هدر	توضیحات
x-ratelimit-limit-requests	حداکثر تعداد درخواست‌های مجاز در پنجره زمانی فعلی
x-ratelimit-remaining-requests	تعداد درخواست‌های باقی‌مانده در پنجره زمانی فعلی
x-ratelimit-reset-requests	زمانی که پنجره محدودیت نرخ فعلی بازنشانی می‌شود
x-ratelimit-limit-tokens	حداکثر تعداد توکن‌های مجاز در پنجره زمانی فعلی
x-ratelimit-remaining-tokens	تعداد توکن‌های باقی‌مانده در پنجره زمانی فعلی
x-ratelimit-reset-tokens	زمانی که پنجره محدودیت نرخ توکن بازنشانی می‌شود

مدیریت خطاهای محدودیت نرخ

هنگامی که از محدودیت نرخ فراتر می‌روید، API کد وضعیت 429 Too Many Requests را به همراه اطلاعاتی در مورد زمان تلاش مجدد برمی‌گرداند:

{
  "error": {
    "message": "Rate limit exceeded for requests. Please try again in 30s.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

پاسخ ممکن است شامل هدر Retry-After باشد که تعداد ثانیه‌هایی را که باید قبل از تلاش مجدد صبر کنید، نشان می‌دهد:

Retry-After: 30

بهترین شیوه‌ها برای مدیریت محدودیت‌های نرخ

پیاده‌سازی عقب‌نشینی نمایی (Exponential Backoff)

هنگامی که با خطای محدودیت نرخ مواجه می‌شوید، از عقب‌نشینی نمایی برای تلاش مجدد درخواست استفاده کنید:

مثال Chat Completions

Python

import os
import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)


def with_backoff(call, max_retries=5, initial_delay=1, max_delay=60):
    delay = initial_delay
    for attempt in range(max_retries + 1):
        try:
            return call()
        except RateLimitError as error:
            if attempt == max_retries:
                raise
            retry_after = (
                int(error.headers.get("retry-after", 0)) if error.headers else 0
            )
            delay = max(delay, retry_after)
            sleep_time = delay + random.uniform(0, delay * 0.5)
            print(f"Rate limit exceeded. Retrying in {sleep_time:.2f}s...")
            time.sleep(sleep_time)
            delay = min(delay * 2, max_delay)


completion = with_backoff(
    lambda: client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": "سلام!"}],
    )
)

print(completion.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

async function withBackoff(call, maxRetries = 5, initialDelay = 1000, maxDelay = 60000) {
  let delay = initialDelay;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await call();
    } catch (error) {
      if (error.status !== 429 || attempt === maxRetries) throw error;

      const retryAfter = error.headers?.["retry-after"]
        ? Number(error.headers["retry-after"]) * 1000
        : 0;
      delay = Math.max(delay, retryAfter);
      const sleepTime = delay + Math.random() * delay * 0.5;
      console.log(`Rate limit exceeded. Retrying in ${sleepTime / 1000}s...`);
      await new Promise((resolve) => setTimeout(resolve, sleepTime));
      delay = Math.min(delay * 2, maxDelay);
    }
  }
}

const completion = await withBackoff(() =>
  client.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: "سلام!" }],
  }),
);

console.log(completion.choices[0].message.content);

Bash

#!/usr/bin/env bash
set -euo pipefail

payload='{"model":"gpt-5.5","messages":[{"role":"user","content":"سلام!"}]}'
delay=1

for attempt in 0 1 2 3 4 5; do
  response=$(curl -sS -w "\n%{http_code}" https://api.avalai.ir/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AVALAI_API_KEY" \
    -d "$payload")
  status="${response##*$'\n'}"
  body="${response%$'\n'*}"

  if [[ $status == "200" ]]; then
    echo "$body"
    break
  fi

  if [[ $status != "429" || $attempt == "5" ]]; then
    echo "$body" >&2
    exit 1
  fi

  echo "Rate limit exceeded. Retrying in ${delay}s..." >&2
  sleep "$delay"
  delay=$((delay * 2 > 60 ? 60 : delay * 2))
done

نسخه معادل Responses API

همین الگوی تلاش مجدد را برای /v1/responses استفاده کنید؛ messages به input تبدیل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

Python

response = with_backoff(
    lambda: client.responses.create(
        model="gpt-5.5",
        input="سلام!",
    )
)

print(response.output_text)

JavaScript

const response = await withBackoff(() =>
  client.responses.create({
    model: "gpt-5.5",
    input: "سلام!",
  }),
);

console.log(response.output_text);

Bash

#!/usr/bin/env bash
set -euo pipefail

payload='{"model":"gpt-5.5","input":"سلام!"}'
delay=1

for attempt in 0 1 2 3 4 5; do
  response=$(curl -sS -w "\n%{http_code}" https://api.avalai.ir/v1/responses \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AVALAI_API_KEY" \
    -d "$payload")
  status="${response##*$'\n'}"
  body="${response%$'\n'*}"

  if [[ $status == "200" ]]; then
    echo "$body"
    break
  fi

  if [[ $status != "429" || $attempt == "5" ]]; then
    echo "$body" >&2
    exit 1
  fi

  echo "Rate limit exceeded. Retrying in ${delay}s..." >&2
  sleep "$delay"
  delay=$((delay * 2 > 60 ? 60 : delay * 2))
done

پیاده‌سازی محدودیت نرخ در سمت خودتان

به طور فعال نرخ درخواست خود را محدود کنید تا از برخورد به محدودیت‌های نرخ API جلوگیری کنید:

مثال پایتون با الگوریتم سطل توکن (Token Bucket)

import os
import time
import threading
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)


class TokenBucket:
    """الگوریتم سطل توکن برای محدودیت نرخ."""

    def __init__(self, tokens_per_second, max_tokens):
        self.tokens_per_second = tokens_per_second
        self.max_tokens = max_tokens
        self.tokens = max_tokens
        self.last_refill_time = time.time()
        self.lock = threading.Lock()

    def get_token(self, tokens=1):
        """دریافت توکن از سطل. در صورت موجود بودن توکن‌ها True و در غیر این صورت False برمی‌گرداند."""
        with self.lock:
            self._refill()
            if self.tokens >= tokens:
                self.tokens -= tokens
                return True
            return False

    def _refill(self):
        """پر کردن مجدد سطل توکن بر اساس زمان سپری شده."""
        now = time.time()
        elapsed = now - self.last_refill_time
        new_tokens = elapsed * self.tokens_per_second
        if new_tokens > 0:
            self.tokens = min(self.tokens + new_tokens, self.max_tokens)
            self.last_refill_time = now


def make_chat_request(prompt):
    """ارسال درخواست Chat Completions با محدودکننده محلی."""
    while not rate_limiter.get_token():
        time.sleep(0.1)

    return client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": prompt}],
    )


def make_responses_request(prompt):
    """نسخه معادل Responses API با همان محدودکننده محلی."""
    while not rate_limiter.get_token():
        time.sleep(0.1)

    return client.responses.create(model="gpt-5.5", input=prompt)


# مثال استفاده: ۱۰ درخواست در ثانیه، حداکثر burst برابر ۵۰
rate_limiter = TokenBucket(10, 50)

در صورت امکان درخواست‌ها را دسته‌بندی کنید

برای عملیاتی مانند تعبیه‌سازی‌‌ها، چندین ورودی را در یک درخواست واحد دسته‌بندی کنید:

# به جای ارسال ۱۰ درخواست جداگانه
texts = [
    "روباه قهوه‌ای سریع از روی سگ تنبل می‌پرد.",
    "پنج جادوگر بوکسور به سرعت می‌پرند.",
    # ... ۸ متن دیگر
]

# ارسال یک درخواست دسته‌ای واحد
response = client.embeddings.create(model="text-embedding-3-small", input=texts)

# پردازش همه تعبیه‌سازی‌‌ها به یکباره
embeddings = [item.embedding for item in response.data]

نظارت بر استفاده خود

استفاده از API خود را برای جلوگیری از خطاهای غیرمنتظره محدودیت نرخ پیگیری کنید:

def track_usage(response):
    """پیگیری استفاده از API از هدرهای پاسخ."""
    headers = response.headers

    # محدودیت‌های نرخ مبتنی بر درخواست
    requests_limit = int(headers.get("x-ratelimit-limit-requests", 0))
    requests_remaining = int(headers.get("x-ratelimit-remaining-requests", 0))
    requests_reset = int(headers.get("x-ratelimit-reset-requests", 0))

    # محدودیت‌های نرخ مبتنی بر توکن
    tokens_limit = int(headers.get("x-ratelimit-limit-tokens", 0))
    tokens_remaining = int(headers.get("x-ratelimit-remaining-tokens", 0))
    tokens_reset = int(headers.get("x-ratelimit-reset-tokens", 0))

    # محاسبه درصد استفاده
    requests_usage_pct = (
        100 - (requests_remaining / requests_limit * 100) if requests_limit else 0
    )
    tokens_usage_pct = (
        100 - (tokens_remaining / tokens_limit * 100) if tokens_limit else 0
    )

    print(
        f"Requests: {requests_remaining}/{requests_limit} ({requests_usage_pct:.1f}% used)"
    )
    print(f"Tokens: {tokens_remaining}/{tokens_limit} ({tokens_usage_pct:.1f}% used)")

    # هشدار در صورت بالا بودن استفاده
    if requests_usage_pct > 80 or tokens_usage_pct > 80:
        print("WARNING: API usage is high!")

    return {
        "requests": {
            "limit": requests_limit,
            "remaining": requests_remaining,
            "reset": requests_reset,
            "usage_pct": requests_usage_pct,
        },
        "tokens": {
            "limit": tokens_limit,
            "remaining": tokens_remaining,
            "reset": tokens_reset,
            "usage_pct": tokens_usage_pct,
        },
    }


# مثال Chat Completions
raw_response = client.chat.completions.with_raw_response.create(
    model="gpt-5.5", messages=[{"role": "user", "content": "سلام!"}]
)
completion = raw_response.parse()
usage_stats = track_usage(raw_response)
print(completion.choices[0].message.content)

# نسخه معادل Responses API
raw_response = client.responses.with_raw_response.create(model="gpt-5.5", input="سلام!")
response = raw_response.parse()
usage_stats = track_usage(raw_response)
print(response.output_text)

پیاده‌سازی صف درخواست

برای برنامه‌های با حجم بالا، یک صف درخواست پیاده‌سازی کنید:

import queue
import threading
import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

# ایجاد یک صف درخواست
request_queue = queue.Queue()


def process_queue():
    """پردازش درخواست‌ها از صف با محدودیت نرخ."""
    requests_per_minute = 60  # بر اساس سطح خود تنظیم کنید
    request_interval = 60 / requests_per_minute

    while True:
        request_func, callback = request_queue.get()

        try:
            result = request_func()
            if callback:
                callback(result, None)
        except Exception as e:
            if callback:
                callback(None, e)
        finally:
            request_queue.task_done()
            time.sleep(request_interval)


def make_chat_request(prompt):
    def request_func():
        return client.chat.completions.create(
            model="gpt-5.5", messages=[{"role": "user", "content": prompt}]
        )

    def callback(result, error):
        if error:
            print(f"Error: {error}")
        else:
            print(f"Response: {result.choices[0].message.content}")

    # افزودن درخواست به صف
    request_queue.put((request_func, callback))


def make_responses_request(prompt):
    """نسخه معادل Responses API برای همین صف."""
    request_queue.put(
        (
            lambda: client.responses.create(model="gpt-5.5", input=prompt),
            lambda result, error: print(error or result.output_text),
        )
    )


queue_thread = threading.Thread(target=process_queue, daemon=True)
queue_thread.start()

for i in range(10):
    make_chat_request(f"Request {i}: Tell me a fact about space")

استراتژی‌های محدودیت نرخ برای سناریوهای مختلف

برنامه‌های تعاملی

برای برنامه‌های دارای تعامل کاربر:

1. پیاده‌سازی throttling سمت کلاینت برای جلوگیری از ارسال بیش از حد درخواست توسط کاربران
2. نمایش نشانگرهای بارگذاری برای ارائه بازخورد در طول فراخوانی‌های API
3. کش کردن پاسخ‌ها برای پرس‌وجوهای رایج برای کاهش فراخوانی‌های API

پردازش دسته‌ای

هشدار

ویژگی پیاده‌سازی نشده!

این قابلیت در حال حاضر در حال توسعه است و هنوز در AvalAI در دسترس نیست. ما انتشار آن را از طریق کانال‌های رسمی خود اعلام خواهیم کرد. منتظر به‌روزرسانی‌های ما باشید!

برای برنامه‌های پردازش دسته‌ای:

1. زمان‌بندی کارها در ساعات کم‌بار برای جلوگیری از مشکلات محدودیت نرخ
2. پردازش در دسته‌های کوچکتر برای توزیع درخواست‌ها در طول زمان
3. پیاده‌سازی منطق تلاش مجدد با افزایش تاخیر بین دسته‌ها

سیستم‌های با دسترسی‌پذیری بالا

برای سیستم‌هایی که نیاز به دسترسی‌پذیری بالا دارند:

1. پیاده‌سازی چندین کلید API با متعادل‌سازی بار
2. تنظیم مکانیسم‌های جایگزین برای زمانی که به محدودیت‌های نرخ می‌رسید
3. حفظ بودجه توکن/درخواست برای اطمینان از اولویت عملیات حیاتی

ارتقا محدودیت‌های نرخ شما

اگر به‌طور مداوم به محدودیت‌های نرخ برخورد می‌کنید، سریع‌ترین راه‌ها برای افزایش ظرفیت شما این‌هاست:

1. شمارهٔ تلفن خود را تأیید کنید تا فورا از سطح پایه به سطح ۱ ارتقا یابید — بدون نیاز به هیچ شارژی.
2. حساب خود را شارژ کنید تا به سطح ۲ و سطوح بالاتر برسید. سطوح بر اساس شارژ تجمعی محاسبه می‌شوند، پس هر شارژی شما را به ارتقای بعدی نزدیک‌تر می‌کند.
3. پیاده‌سازی خود را بهینه کنید تا فراخوانی‌های غیرضروری API کاهش یابد (دسته‌بندی درخواست‌ها، کش‌کردن پاسخ‌ها و انتخاب اندازهٔ مدل مناسب همگی کمک می‌کنند).
4. سطح فعلی و پیشرفت خود را در هر زمان از داشبورد حساب کاربری خود بررسی کنید.

ارتقای سطح به‌محض عبور از آستانهٔ بعدی، به‌صورت خودکار و آنی انجام می‌شود — بدون تیکت پشتیبانی، بدون انتظار — و تمام اعتبار شما پس از هر ارتقا برای استفاده از API باقی می‌ماند.

نتیجه‌گیری

مدیریت مؤثر محدودیت نرخ برای ساخت برنامه‌های قابل اعتماد با API AvalAI ضروری است. با پیاده‌سازی استراتژی‌های ذکر شده در این راهنما، می‌توانید اختلالات ناشی از محدودیت نرخ را به حداقل برسانید و تجربه روانی را برای کاربران خود تضمین کنید.

به یاد داشته باشید که محدودیت‌های نرخ ممکن است با تکامل API در طول زمان تغییر کنند. همیشه برای آخرین اطلاعات در مورد محدودیت‌های نرخ به به‌روزترین مستندات مراجعه کنید.