استعلام استخدام المفتاح

الوظيفة

استرجاع استهلاك حصة مفتاح Bearer الحالي: إجمالي الممنوح، والمستخدم، والمتاح، وعلامة اللامحدودية، وقيود النماذج، ووقت الانتهاء.

📮 نقطة الوصول

GET /api/usage/token

• تتطلب ترويسة Authorization
• تعيد معلومات الاستخدام الخاصة بالمفتاح المستخدم في الطلب الحالي

🔐 المصادقة

أدرج الترويسة التالية للمصادقة بمفتاح API:

Authorization: Bearer $WS_API_KEY

• البادئة sk- مقبولة لكنها اختيارية؛ يوحّدها الخادم تلقائيًا
• غياب ترويسة Authorization أو عدم صلاحيتها يعيد 401

💡 مثال على الطلب

curl -X GET http://baseurl/api/usage/token \
  -H "Authorization: Bearer $WS_API_KEY"

✅ مثال على استجابة ناجحة

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "Default Token",
    "total_granted": 1000000,
    "total_used": 12345,
    "total_available": 987655,
    "unlimited_quota": false,
    "model_limits": {
      "gpt-5.4-mini": true
    },
    "model_limits_enabled": false,
    "expires_at": 0
  }
}

❗ أمثلة على استجابات الخطأ

• غياب ترويسة Authorization:

{
  "success": false,
  "message": "No Authorization header"
}

• نظام مصادقة غير صالح (غير Bearer):

{
  "success": false,
  "message": "Invalid Bearer token"
}

• فشل جلب المفتاح (غير صالح أو محذوف مثلًا):

{
  "success": false,
  "message": "token not found"
}

🧾 وصف الحقول (data)

• ‏object: دائمًا token_usage
• ‏name: اسم المفتاح
• ‏total_granted: إجمالي الممنوح (= المستخدم + المتاح)
• ‏total_used: الحصة المستخدمة
• ‏total_available: الحصة المتبقية المتاحة
• ‏unlimited_quota: هل يملك المفتاح حصة غير محدودة
• ‏model_limits: قائمة النماذج المسموح بها
• ‏model_limits_enabled: هل قيود النماذج مفعّلة
• ‏expires_at: طابع انتهاء الصلاحية (Unix بالثواني). القيمة 0 تعني عدم الانتهاء (يحوّل الخادم -1 إلى 0).