هر درخواست به API با یک کلید پروژه احراز هویت می‌شود. کلید را از پنل کاربری ← «API هوش مصنوعی» ← پروژهٔ موردنظر بسازید.
کلید با پیشوند sk-ntz-v1- شروع می‌شود و پس از آن ۴۰ کاراکتر تصادفی دارد.
ارسال کلید
کلید را در هدر Authorization با طرح Bearer بفرستید — دقیقاً همان‌طور که برای OpenAI می‌فرستید:
Authorization: Bearer sk-ntz-v1-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX# معادل (برای ابزارهایی که هدر Authorization را پشتیبانی نمی‌کنند):
X-API-Key: sk-ntz-v1-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXدر SDK رسمی OpenAI کافی است متغیرهای محیطی زیر را تنظیم کنید تا بدون هیچ تغییری در کد، درخواست‌ها به نِت اَرز بروند:
# .env
NETARZ_API_KEY=sk-ntz-v1-...
# اگر از SDK رسمی OpenAI استفاده می‌کنید، همین دو متغیر کافی است:
OPENAI_API_KEY=sk-ntz-v1-...
OPENAI_BASE_URL=https://netarz.ir/api/ai/v1ساختار حساب
| سطح | چیست | چه چیزی روی آن تنظیم می‌شود |
|---|---|---|
| حساب | اعتبار دلاری شما (یک حساب برای هر کاربر نِت اَرز) | موجودی، محدودیت همزمانی، سقف مصرف روزانه (در صورت تعیین توسط پشتیبانی) |
| پروژه | یک محصول یا محیط (مثلاً «ربات تلگرام»، «سایت — production») | بودجهٔ ماهانه، مدل‌های مجاز، فعال/غیرفعال |
| کلید | اعتبارنامهٔ یک سرویس یا سرور خاص داخل پروژه | مدل‌های مجاز، IPهای مجاز، RPM اختصاصی، سقف هزینه، تاریخ انقضا، ابطال |
هر درخواست به پروژه و کلیدی که با آن ارسال شده نسبت داده می‌شود؛ گزارش مصرف به همین تفکیک در دسترس است.
چرخهٔ عمر کلید
- ساخت: مقدار کامل کلید فقط یک بار نمایش داده می‌شود. نِت اَرز فقط هش SHA-256 کلید را نگه می‌دارد و نمی‌تواند آن را دوباره به شما نشان دهد.
- محدود کردن: فهرست مدل‌های مجاز (خالی = همهٔ مدل‌های مجاز پروژه)، فهرست IP مجاز (خالی = همهٔ IPها)، سقف هزینهٔ کل کلید و تاریخ انقضا.
- غیرفعال کردن: کلید موقتاً پذیرفته نمی‌شود (
api_key_disabled) و می‌توانید دوباره فعالش کنید. - ابطال: دائمی است (
api_key_revoked). برای چرخش کلید، ابتدا کلید جدید بسازید، آن را مستقر کنید و سپس قدیمی را باطل کنید.
بررسی کلید و موجودی
برای اطمینان از درستی کلید و دیدن موجودی و محدودیت‌های مؤثر روی آن، GET /me را صدا بزنید:
curl https://netarz.ir/api/ai/v1/me \
-H "Authorization: Bearer $NETARZ_API_KEY"{
"object": "account",
"balance": { "usd": "12.345678", "usd_display": "$12.3457", "toman_estimate": 2469136 },
"status": "active",
"project": { "id": 7, "name": "ربات تلگرام" },
"key": {
"name": "production",
"prefix": "sk-ntz-v1-ab12",
"rpm_limit": 60,
"spend_limit_usd": null,
"spent_usd": "3.120000",
"expires_at": null
},
"limits": { "concurrency": 8, "max_request_kb": 20480 }
}خطاهای احراز هویت
| HTTP | code | معنا |
|---|---|---|
| 401 | missing_api_key | هدر Authorization (یا X-API-Key) ارسال نشده است. |
| 401 | invalid_api_key | کلید وجود ندارد یا اشتباه است. پس از ۲۰ کلید اشتباه در ۱۰ دقیقه، آن IP موقتاً مسدود می‌شود. |
| 401 | api_key_revoked | کلید باطل شده است؛ کلید جدید بسازید. |
| 401 | api_key_expired | تاریخ انقضای کلید گذشته است. |
| 401 | api_key_disabled | کلید از پنل غیرفعال شده است. |
| 403 | ip_not_allowed | IP شما در فهرست IPهای مجاز این کلید نیست. |
| 403 | model_not_allowed | این کلید یا پروژه اجازهٔ استفاده از مدل درخواستی را ندارد. |
| 429 | too_many_failed_attempts | تلاش‌های ناموفق بیش از حد از این IP؛ چند دقیقه صبر کنید. |
نکات امنیتی
هر کسی که کد فرانت‌اند شما را ببیند می‌تواند با اعتبار شما درخواست بفرستد. همیشه از سرور خودتان (یا یک تابع بدون سرور) به نِت اَرز وصل شوید و کلید را در متغیر محیطی نگه دارید.
- برای هر محیط (development / staging / production) و هر سرویس، کلید جداگانه بسازید تا ابطال یک کلید بقیه را از کار نیندازد.
- برای کلیدهای سرور، IPهای مجاز را تنظیم کنید (IP دقیق، پیشوند مثل
185.12.34.یا CIDR مثل185.12.34.0/24). - برای هر کلید سقف هزینه و برای هر پروژه بودجهٔ ماهانه بگذارید تا یک باگ یا نشت کلید، کل اعتبار را خرج نکند.
- مدل‌های مجاز را به آن‌هایی که واقعاً استفاده می‌کنید محدود کنید.
- اگر گمان می‌کنید کلیدی لو رفته، بلافاصله آن را باطل کنید و در گزارش درخواست‌ها، IP و زمان استفاده‌ها را بررسی کنید.