البدء

المصادقة

مصادقة طلبات TokenLab API باستخدام مفتاح API

مفاتيح API

تتطلب استدعاءات النماذج والموارد الخاصة مفتاح API. تعمل نقاط نهاية الاكتشاف العامة مثل GET /v1/models و GET /v1/models/{model} بدون مفتاح. لا يعني نجاح استجابة الاكتشاف أن مفتاحك يعمل؛ اتبع دليل البدء السريع (Quickstart) لإرسال طلب نموذج. استخدم المفتاح الكامل المحفوظ؛ البادئة الموجودة في قائمة المفاتيح لا يمكنها إجراء المصادقة.

بالنسبة لنقاط النهاية المتوافقة مع OpenAI، أرسله كالتالي:

Authorization: Bearer sk-your-api-key

بالنسبة لطلبات /v1/messages المتوافقة مع Anthropic، يمكنك أيضاً استخدام:

x-api-key: sk-your-api-key

تقبل طلبات /v1beta/* المتوافقة مع Gemini أيضاً x-goog-api-key: sk-your-api-key. يفضل استخدام الترويسة (header) بدلاً من معامل الاستعلام ?key=، لأن عناوين URL غالباً ما ينتهي بها المطاف في السجلات (logs).

رموز الإدارة (Management Tokens)

تستخدم نقاط نهاية Management API نوعاً منفصلاً من الرموز:

Authorization: Bearer mt-your-management-token

استخدم رموز الإدارة فقط مع نقاط النهاية /v1/management/*. افتح API → Tokens لمساحة العمل المحددة لإنشاء رمز أو استبداله. احفظ الرمز بالكامل عند ظهوره؛ حيث يتم عرضه مرة واحدة فقط بعد الإنشاء أو الاستبدال.

لا يمكن استخدام رموز الإدارة لاستنتاج النماذج، ولا يمكن استخدام مفاتيح API القياسية sk-... لـ Management API.

الحصول على مفتاح API

  1. سجل الدخول إلى TokenLab Console
  2. افتح API Keys
  3. أنشئ مفتاحاً جديداً
  4. امنحه اسماً وصفياً
  5. انسخه فوراً لأنه يظهر مرة واحدة فقط
  • لا تقم أبداً بكشف مفاتيح API في كود جانب العميل (client-side code)
  • لا تقم أبداً برفع مفاتيح API إلى أنظمة التحكم في الإصدار
  • استخدم متغيرات البيئة أو مدير الأسرار (secret manager)
  • قم بتدوير المفاتيح بشكل دوري
  • احذف المفاتيح غير المستخدمة

استخدام مفتاح API

راجع البدء السريع للحصول على متغيرات البيئة وأول طلب كامل. استخدم الـ SDK المطابق لـ API format الذي اخترته؛ احتفظ بالمفاتيح على الخادم.

إعدادات المفتاح

يمكنك ضبط هذه الإعدادات لكل مفتاح API في Console، ومن خلال واجهة برمجة تطبيقات الإدارة:

الإعدادالوصف
حد الإنفاقNo limit يسمح للمفتاح باستخدام رصيد مساحة العمل. Fixed limit يجعل المفتاح يعيد 402 quota_exceeded بعد الوصول إلى المبلغ المحدد.
النماذج المسموح بهايمكن للمفتاح استدعاء هذه النماذج فقط. النماذج الأخرى تعيد 403 model_not_allowed. تركها فارغة يعني عدم وجود قيود على مستوى المفتاح.
خيار التسليمAuto أو Verified أو Official للطلبات الصادرة من هذا المفتاح. تركها فارغة يستخدم الإعداد الافتراضي لمساحة العمل. راجع الفواتير والتسعير.
تاريخ الانتهاءبعد هذا الوقت، يعيد المفتاح 401 expired_api_key.
الحالةالمفتاح inactive (المتوقف مؤقتاً) يعيد 401 invalid_api_key. المفتاح revoked لا يمكن تفعيله مرة أخرى.

بادئة المفتاح

تبدأ جميع مفاتيح TokenLab API بـ sk-.

استجابات الخطأ

رمز الحالةالنوعالكودالوصف
401invalid_api_keyinvalid_api_keyمفتاح API مفقود، غير صالح، غير نشط، أو تم إلغاؤه
401expired_api_keyexpired_api_keyانتهت صلاحية المفتاح
402insufficient_balanceinsufficient_balanceرصيد الحساب غير كافٍ
402quota_exceededquota_exceededتم الوصول إلى حد استخدام مفتاح API
403permission_errormodel_not_allowedالمفتاح غير مسموح له باستخدام النموذج المطلوب
403permission_erroruser_suspended, account_restrictedالحساب لا يمكنه استخدام API
429rate_limit_exceededrate_limit_exceededالكثير من محاولات المصادقة الفاشلة من عنوان IP واحد. انتظر Retry-After وقم بإصلاح المفتاح؛ لا تقم بعمل حلقة تكرارية عند ظهور 401

مثال:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

في هذه الصفحة