محدودیتهای کلید: فهرست مدل، نشانی IP، دامنهٔ دسترسی و چرخش کلید
هر کلید میتواند محدودیتهای خودش را داشته باشد: فقط مدلهای مشخص، فقط از نشانیهای IP مشخص، فقط برای فراخوانی مدل یا فقط برای خواندن گزارشها، و با سقف نرخی پایینتر از سقف حساب. کلید را میشود چرخاند: کلید تازه صادر میشود و کلید قبلی تا پایان مهلت کار میکند. هیچکدام بهطور پیشفرض فعال نیست؛ کلیدی که محدودیتی ندارد مثل قبل رفتار میکند. درخواستی که به محدودیت میخورد خطای 403 میگیرد و هزینهای ندارد.
آخرین بهروزرسانی:
فهرست مستندات
مسیرهای API
حساب، کلید و تیم
محدودیتهای کلید · ۱
تنظیمهای یک کلید
| فیلد | پیشفرض | معنی |
|---|---|---|
allowed_models | خالی: همهٔ مدلها | تا ۱۰۰ نام دقیق مدل، یا پیشوندی که به * ختم میشود (مثل claude-*) |
allowed_ips | خالی: هر نشانی | تا ۵۰ نشانی IPv4 یا IPv6 یا بازهٔ CIDR |
scope | full | full، 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.
| وضعیت | کد | کِی |
|---|---|---|
403 | key_model_not_allowed | مدل در فهرست کلید نیست |
403 | key_ip_not_allowed | نشانی فرستنده در فهرست کلید نیست |
403 | key_scope_denied | مسیر بیرون از دامنهٔ کلید است |