کلیدهای API
کلید API، شناسهای است که به دروازه هوش مصنوعی میگوید شما چه کسی هستید و اجازه دسترسی به چه چیزهایی را دارید. تمام درخواستها با این کلید احراز هویت میشوند و هزینه آنها از کیف پول شما کسر میشود.
مدیریت کلیدها از بخش هوش مصنوعی → کلیدهای API در کنسول کاربری انجام میشود.
ساخت کلید جدید
روی دکمه + ایجاد کلید جدید کلیک کنید. فرم ساخت کلید شامل این فیلدهاست:
نام کلید (الزامی)
نامی برای شناسایی کلید. این نام فقط برای خود شماست و در درخواستها استفاده نمیشود. توصیه میشود نام گویا انتخاب کنید تا بعداً بدانید هر کلید کجا استفاده شده:
- ✅
اپلیکیشن موبایل - پروداکشن - ✅
تست محلی - ❌
کلید ۱
مدلهای مجاز
میتوانید مشخص کنید این کلید فقط به مدلهای خاصی دسترسی داشته باشد. اگر هیچ مدلی انتخاب نکنید، کلید به همه مدلها دسترسی خواهد داشت.
این قابلیت برای کنترل هزینه بسیار مفید است — مثلاً میتوانید کلیدی بسازید که فقط به مدلهای ارزانقیمت دسترسی داشته باشد.
انقضا
تاریخی که پس از آن کلید بهطور خودکار از کار میافتد:
| گزینه | توضیح |
|---|---|
| بدون انقضا | کلید تا زمانی که خودتان حذفش کنید معتبر است |
| ۳۰ روز | مناسب برای تست و پروژههای کوتاهمدت |
| ۹۰ روز | مناسب برای پروژههای میانمدت |
| ۱ سال | مناسب برای سرویسهای پایدار |
تعیین تاریخ انقضا یک اقدام امنیتی خوب است. حتی برای سرویسهای دائمی، تعیین انقضای یکساله شما را وادار میکند کلیدها را بهصورت دورهای تعویض کنید.
تنظیمات پیشرفته
بخش تنظیمات پیشرفته در فرم ساخت کلید، چهار محدودیت اختیاری در اختیار شما میگذارد.
سقف بودجه
حداکثر مبلغی (به تومان) که این کلید مجاز است مصرف کند. وقتی مصرف کلید به این سقف برسد، درخواستهای بعدی رد میشوند — حتی اگر کیف پول شما موجودی داشته باشد.
این مؤثرترین محافظ در برابر مصرف ناخواسته است. اگر کلیدی لو برود یا کدی دچار حلقه بینهایت شود، ضرر شما به همان سقف محدود میماند.
دوره تجدید بودجه
مشخص میکند سقف بودجه چه زمانی صفر شود:
| گزینه | رفتار |
|---|---|
| هرگز | سقف بودجه یکبار مصرف است؛ پس از اتمام، کلید از کار میافتد |
| ماهانه | هر ماه بودجه از نو شروع میشود |
| هفتگی | هر هفته بودجه از نو شروع میشود |
مثال: سقف بودجه ۵۰۰۰۰۰ تومان با تجدید ماهانه یعنی این کلید حداکثر ماهی ۵۰۰ هزار تومان مصرف میکند.
محدودیت درخواست در دقیقه (RPM)
حداکثر تعداد درخواستی که این کلید در هر دقیقه میتواند ارسال کند. با عبور از این حد، پاسخ 429 دریافت میکنید.
کاربرد: جلوگیری از هجوم ناگهانی درخواستها، مثلاً وقتی یک باگ باعث ارسال مکرر درخواست میشود.
محدودیت توکن در دقیقه (TPM)
حداکثر تعداد توکنی که این کلید در هر دقیقه میتواند مصرف کند. برخلاف RPM که تعداد درخواست را میشمارد، TPM حجم واقعی مصرف را کنترل میکند.
یک درخواست با متن بسیار طولانی میتواند بهاندازه صدها درخواست کوتاه توکن مصرف کند. اگر نگران هزینه هستید، TPM معیار دقیقتری است؛ اگر نگران فشار روی سرویس هستید، RPM.
کلید پس از ساخت
پس از تأیید فرم، کلید در یک پنجره نمایش داده میشود.
کلید کامل تنها در همین لحظه قابل مشاهده است. پس از بستن پنجره، دیگر قابل بازیابی نیست — در فهرست کلیدها فقط چهار رقم آخر آن نمایش داده میشود.
اگر کلید را گم کردید، باید کلید قدیمی را حذف و کلید جدیدی بسازید.
روی دکمه کپی کلید بزنید و آن را در جای امنی ذخیره کنید.
فهرست کلیدها
در جدول کلیدها این اطلاعات نمایش داده میشود:
| ستون | توضیح |
|---|---|
| نام کلید | نامی که هنگام ساخت انتخاب کردهاید |
| کلید | چهار رقم آخر کلید، بهصورت ••••xxxx |
| وضعیت | فعال / منقضی / غیرفعال |
| بودجه | سقف بودجه تعیینشده |
| انقضا | تاریخ انقضای کلید |
| عملیات | ویرایش و حذف |
وضعیت کلیدها
- فعال — کلید کار میکند
- منقضی — تاریخ انقضا گذشته است؛ درخواستها رد میشوند
- غیرفعال — کلید موقتاً از کار افتاده است
ویرایش کلید
با کلیک روی ویرایش، میتوانید نام، مدلهای مجاز، بودجه، محدودیتهای نرخ و تاریخ انقضا را تغییر دهید.
خود مقدار کلید قابل تغییر نیست. اگر میخواهید کلید عوض شود، باید کلید جدید بسازید و قدیمی را حذف کنید.
حذف کلید
با کلیک روی حذف و تأیید، کلید بلافاصله از کار میافتد.
حذف کلید قابل بازگشت نیست. هر برنامهای که از این کلید استفاده میکند، بلافا صله با خطای 401 مواجه میشود. پیش از حذف، مطمئن شوید کلید در جایی استفاده نمیشود.
توصیههای امنیتی
کلید را در کد قرار ندهید. از متغیر محیطی استفاده کنید:
# ❌ اشتباه
client = OpenAI(api_key="sk-xxxxxxxxxxxx")
# ✅ درست
client = OpenAI(api_key=os.environ["NOVIN_API_KEY"])
کلید را در گیت کامیت نکنید. فایل .env را به .gitignore اضافه کنید:
.env
.env.local
برای هر محیط، کلید جداگانه بسازید. کلید توسعه، تست و پروداکشن را از هم جدا کنید تا اگر یکی لو رفت، بقیه در امان بمانند.
کلید را در مرورگر استفاده نکنید. اگر کلید را در کد سمت کاربر (JavaScript مرورگر یا اپلیکیشن موبایل) قرار دهید، هر کسی میتواند آن را استخراج کند. درخواستها را از سرور خودتان ارسال کنید.
اگر کلید لو رفت، فوراً حذفش کنید. حذف کلید سریعترین راه توقف مصرف است.
گام بعدی
- مدلها — انتخاب مدل و شناسههای معتبر
- مصرف و صورتحساب — پیگیری مصرف هر کلید
- مرجع API — استفاده از کلید در درخواستها