۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مستندات API

محدودیت‌های کلید: فهرست مدل، نشانی IP، دامنهٔ دسترسی و چرخش کلید

هر کلید می‌تواند محدودیت‌های خودش را داشته باشد: فقط مدل‌های مشخص، فقط از نشانی‌های IP مشخص، فقط برای فراخوانی مدل یا فقط برای خواندن گزارش‌ها، و با سقف نرخی پایین‌تر از سقف حساب. کلید را می‌شود چرخاند: کلید تازه صادر می‌شود و کلید قبلی تا پایان مهلت کار می‌کند. هیچ‌کدام به‌طور پیش‌فرض فعال نیست؛ کلیدی که محدودیتی ندارد مثل قبل رفتار می‌کند. درخواستی که به محدودیت می‌خورد خطای 403 می‌گیرد و هزینه‌ای ندارد.

آخرین به‌روزرسانی:

فهرست مستندات

محدودیت‌های کلید · ۱

تنظیم‌های یک کلید

فیلدهای `controls`
فیلدپیش‌فرضمعنی
allowed_modelsخالی: همهٔ مدل‌هاتا ۱۰۰ نام دقیق مدل، یا پیشوندی که به * ختم می‌شود (مثل claude-*)
allowed_ipsخالی: هر نشانیتا ۵۰ نشانی IPv4 یا IPv6 یا بازهٔ CIDR
scopefullfull، inference یا usage
rate_limit_per_minخالی: سقف حسابسقف نرخ خود کلید، از یک تا سقف حساب

این تنظیم‌ها را هنگام ساختن یا ویرایش کلید در کلیدهای API می‌گذاری. در API حساب هر کلید یک شیء controls با همین فیلدها دارد، به‌علاوهٔ effective_rate_limit_per_min (همان عدد هدر X-RateLimit-Limit)، rotated_at و previous_secret_expires_at.

محدودیت‌های کلید · ۲

فهرست مدل

  • اگر کلید فهرست مدل داشته باشد و مدل درخواست در آن نباشد، پاسخ 403 با کد key_model_not_allowed است. چیزی رزرو، حساب یا فرستاده نمی‌شود.
  • روی همهٔ مسیرهای حساب‌شونده سنجیده می‌شود: چت، Responses، امبدینگ، تصویر، صدا، ویدیو، کلید موقت صوت زنده، مسیر Anthropic و مسیر Gemini (مدل درون نشانی).
  • GET /v1/models و گرفتن وضعیت و دانلود نتیجه‌ها محدود نمی‌شوند.
  • در دسته‌های پیام Anthropic مدل هر درخواست دسته هنگام فرستادن سنجیده می‌شود و اگر یکی در فهرست نباشد کل دسته رد می‌شود. چنین کلیدی زیر /anthropic/v1/messages/batches فقط فرستادن دسته و /{id}/cancel را می‌تواند POST کند.
  • کلیدی که فهرست مدل دارد باید مدل را یک بار بنویسد: بدنهٔ JSON با دو کلید model (با هر بزرگی و کوچکی حروف) یا فرم multipart با دو بخش model خطای 400 با کد invalid_request می‌گیرد؛ در دسته، requests، هر params و هر model هم همین‌طور.
  • مقایسه با فهرست به بزرگی و کوچکی حروف حساس نیست، ولی فهرست قیمت هست: نامی با حروف بزرگ (مثل GPT-4o-mini) از فهرست کلید می‌گذرد و بعد خطای 402 با کد model_not_priced می‌گیرد. نام مدل را همیشه همان‌طور بنویس که GET /v1/models برمی‌گرداند.
  • پیشوند سازنده (openai/gpt-4o) یا نام بلندتر (نسخهٔ تاریخ‌دار) با نام کوتاه یکی حساب نمی‌شود؛ برای یک خانواده از پیشوند با * استفاده کن.
  • نام بازنشسته‌ای که به مدل جانشین می‌رود مجاز است اگر هر کدام از دو نام در فهرست باشد.

محدودیت‌های کلید · ۳

فهرست نشانی IP

  • درخواست از نشانی‌ای که در فهرست کلید نیست، روی هر مسیری، 403 با کد key_ip_not_allowed می‌گیرد و در سقف نرخ شمرده نمی‌شود.
  • نشانی همانی است که سرور ما برای اتصال می‌بیند؛ هدرهایی مثل X-Forwarded-For که کلاینت می‌فرستد نادیده گرفته می‌شوند.
  • کلیدی که فهرست نشانی دارد فقط روی https://1xai.ir کار می‌کند. روی https://api.1xai.ir نشانی فرستنده برای دروازه معلوم نیست و چنین کلیدی آن‌جا key_ip_not_allowed می‌گیرد.
  • نشانی‌های خصوصی، loopback و بازهٔ /0 پذیرفته نمی‌شوند.

محدودیت‌های کلید · ۴

دامنهٔ دسترسی

دامنه‌ها
دامنهچه کاری می‌تواند
fullهمهٔ مسیرها؛ رفتار هر کلید پیش از این
inferenceهمه چیز جز API حساب
usageفقط GET روی API حساب (/v1/usage، /v1/usage/summary، /v1/usage/export، /v1/wallet/*، /v1/keys، /v1/keys/{id}، /v1/keys/current و /v1/sla/credits)؛ نه فراخوانی مدل و نه GET /v1/models

بیرون از دامنه، پاسخ 403 با کد key_scope_denied است. کلید usage برای داشبورد مالی یا اسکریپت گزارش‌گیری مناسب است: حتی اگر لو برود نمی‌تواند خرج کند.

محدودیت‌های کلید · ۵

سقف نرخ خود کلید

سقف خود کلید از سقف حساب بالاتر نمی‌شود. هدر X-RateLimit-Limit سقفی را می‌گوید که الان روی کلید اعمال می‌شود (محدودیت نرخ).

محدودیت‌های کلید · ۶

چرخش کلید

  • چرخش برای همان کلید یک رمز تازه صادر می‌کند: شناسه، نام، محدودیت‌ها، انقضا، سقف خرج، خرج تا این لحظه و سابقهٔ مصرف می‌مانند. رمز تازه یک بار نمایش داده می‌شود.
  • رمز قبلی تا پایان مهلت کار می‌کند: از صفر تا ۱۶۸ ساعت، پیش‌فرض ۲۴ ساعت. با مهلت صفر همان لحظه از کار می‌افتد.
  • چرخش دوباره، رمز قدیمی‌ای را که هنوز در مهلت است همان لحظه از کار می‌اندازد. ابطال کلید هر دو رمز را از کار می‌اندازد.
  • کلید باطل یا منقضی را نمی‌شود چرخاند (409 با کد key_not_active).

محدودیت‌های کلید · ۷

ترتیب بررسی‌ها و کدهای خطا

ترتیب: اول 401 (کلید نادرست، باطل، منقضی یا به سقف خرج رسیده)، بعد key_ip_not_allowed، بعد key_scope_denied، بعد 429، و بعد بررسی‌های خود مسیر، از جمله key_model_not_allowed.

کدهای خطای محدودیت کلید
وضعیتکدکِی
403key_model_not_allowedمدل در فهرست کلید نیست
403key_ip_not_allowedنشانی فرستنده در فهرست کلید نیست
403key_scope_deniedمسیر بیرون از دامنهٔ کلید است