شروع کار

احراز هویت

کلید API را چگونه بفرستید، قالب آن چیست، چه چیزی باعث رد شدن کلید می‌شود و چطور آن را امن نگه دارید.

هر درخواست به /v1 و /v1beta باید کلید API داشته باشد. کلید به یک حساب وصل است و مصرف از کیف اعتبار همان حساب کم می‌شود.

قالب کلید

کلید با sk-1ai- شروع می‌شود و بعد از آن ۴۰ نویسه‌ی حرف و عدد انگلیسی دارد. فقط هش کلید ذخیره می‌شود و کلید کامل یک بار هنگام ساخت نشان داده می‌شود. اگر گم شد، باید کلید تازه بسازید.

روش‌های ارسال

روشمسیرها
Authorization: Bearer sk-1ai-…همه‌ی مسیرها
x-api-key: sk-1ai-…همه‌ی مسیرها (برای کتابخانه‌ی Anthropic)
x-goog-api-key: sk-1ai-…فقط /v1beta
?key=sk-1ai-… در آدرسفقط /v1beta

اگر Authorization با Bearer بیاید، همان خوانده می‌شود. در غیر این‌صورت x-api-key و فقط در /v1beta در ادامه x-goog-api-key و پارامتر key بررسی می‌شوند. ارسال کلید در آدرس را فقط برای ابزارهایی استفاده کنید که راه دیگری ندارند، چون آدرس‌ها در لاگ‌ها می‌مانند.

چه چیزی کلید را رد می‌کند

در هر یک از حالت‌های زیر، پاسخ همیشه یکی است: وضعیت 401 و کد invalid_api_key. پیام هم همه‌ی حالت‌ها را یکسان می‌گوید تا نشود کلیدها را حدس زد.

  • کلید وجود ندارد یا با sk-1ai- شروع نمی‌شود.
  • کلید لغو یا معلق شده است.
  • تاریخ انقضای کلید گذشته است.
  • صاحب کلید دیگر فعال نیست (حساب غیرفعال یا حذف‌شده).
json
{
  "error": {
    "message": "Incorrect or inactive API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null,
    "request_id": "6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10"
  }
}

تغییر وضعیت کلید (مثلاً لغو آن) تا حدود یک دقیقه ممکن است در بعضی نمونه‌های سرور دیر اعمال شود.

محدود کردن کلید

برای هر کلید در پنل می‌توانید تنظیم کنید:

  • فهرست مدل‌های مجاز. مدل بیرون از فهرست، 403 با کد model_not_allowed می‌دهد و در GET /v1/models هم دیده نمی‌شود.
  • سقف ماهانه‌ی اعتبار. رسیدن به آن، 402 با کد key_cap_reached می‌دهد.
  • سقف درخواست و توکن در دقیقه و در روز. محدودیت نرخ را ببینید.
  • تاریخ انقضا.

نگهداری امن کلید

  • کلید را در متغیر محیطی یا مدیر رمز نگه دارید و در مخزن کد نگذارید.
  • کلید را در کد سمت کاربر (مرورگر، اپ موبایل) قرار ندهید. درخواست‌ها را از سرور خودتان بفرستید.
  • برای هر محیط یک کلید جدا بسازید، مثلاً توسعه و تولید، و برای هرکدام سقف و مدل‌های مجاز بگذارید.
  • اگر کلیدی لو رفت، در پنل آن را لغو کنید و کلید تازه بسازید.

صفحه‌های مرتبط