البدء
المصادقة
مصادقة طلبات 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
- سجل الدخول إلى TokenLab Console
- افتح API Keys
- أنشئ مفتاحاً جديداً
- امنحه اسماً وصفياً
- انسخه فوراً لأنه يظهر مرة واحدة فقط
- لا تقم أبداً بكشف مفاتيح 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-.
استجابات الخطأ
| رمز الحالة | النوع | الكود | الوصف |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | مفتاح API مفقود، غير صالح، غير نشط، أو تم إلغاؤه |
| 401 | expired_api_key | expired_api_key | انتهت صلاحية المفتاح |
| 402 | insufficient_balance | insufficient_balance | رصيد الحساب غير كافٍ |
| 402 | quota_exceeded | quota_exceeded | تم الوصول إلى حد استخدام مفتاح API |
| 403 | permission_error | model_not_allowed | المفتاح غير مسموح له باستخدام النموذج المطلوب |
| 403 | permission_error | user_suspended, account_restricted | الحساب لا يمكنه استخدام API |
| 429 | rate_limit_exceeded | rate_limit_exceeded | الكثير من محاولات المصادقة الفاشلة من عنوان IP واحد. انتظر Retry-After وقم بإصلاح المفتاح؛ لا تقم بعمل حلقة تكرارية عند ظهور 401 |
مثال:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}