الإدارة

واجهة برمجة تطبيقات الإدارة

التحقق من أرصدة Workspace، وإدارة مفاتيح API، واسترداد بيانات الاستخدام والفوترة

استخدم Management API من الواجهة الخلفية (backend) الخاصة بك أو من خلال أدوات التشغيل الآلي لإدارة TokenLab Workspace. وتعتمد هذه الواجهة على management token، مما يعني أن البرنامج لا يحتاج إلى مفتاح API عادي.

أنشئ management token من خلال لوحة التحكم ← API ← Management Tokens:

Authorization: Bearer mt-your-management-token

تمتلك management tokens ومفاتيح API أدواراً مختلفة. استخدم mt-... فقط مع /v1/management/*، واستخدم sk-... مع واجهات API الخاصة بالنماذج مثل /v1/responses.

نقاط النهاية

نقطة النهايةالطريقةالاستخدام
/v1/management/balanceGETالحصول على رصيد Workspace
/v1/management/api-keysGETسرد مفاتيح API
/v1/management/api-keysPOSTإنشاء مفتاح API
/v1/management/api-keys/{keyId}PATCHتغيير اسمه أو الحد الأقصى أو النماذج أو تاريخ انتهاء الصلاحية أو الحالة
/v1/management/api-keys/{keyId}/usageGETالحصول على سجلات الاستخدام الفردية
/v1/management/api-keys/{keyId}/billingGETالحصول على ملخص الفوترة

مفاتيح API

  • يظهر السر الكامل للمفتاح الجديد فقط ضمن استجابة الإنشاء.
  • إعداد models: [] لا يضيف أي قيود على مستوى النموذج للمفتاح.
  • القيمة limitAmount: null تعني أنه غير محدود. بينما تمنع القيمة 0 المفتاح من تكبد أي إنفاق.
  • المبالغ بعملة USD. يؤدي إرسال CNY إلى إرجاع الخطأ 400 currency_retired.
  • يمكن إعادة تفعيل المفتاح بحالة inactive مرة أخرى. استخدم revoked لإلغاء تنشيط المفتاح نهائياً.

الاستخدام والفوترة

تُرجع /usage سجلات مقسمة إلى صفحات (paginated) وتدعم التصفية حسب النموذج (model)، ومطور النموذج (model maker)، والمشهد (scene)، والتاريخ (date). قد تتضمن السجلات التي تمت تسويتها billing_transaction_id؛ احفظه مع request_id عندما تحتاج إلى مطابقة تكلفة معينة بطلب محدد.

تُرجع /billing الإجماليات مجمعة حسب النموذج، ومطور النموذج، والمشهد، والتاريخ. ولا تتضمن عمليات شحن رصيد Workspace أو الفواتير.

إذا تم تمرير تاريخ فقط في endDate مثل 2026-07-31، فإن ذلك يعني الساعة 00:00 بتوقيت UTC في بداية ذلك اليوم. لتضمين اليوم بأكمله، مرّر تاريخ اليوم التالي أو وقتاً بتنسيق RFC3339 مثل 2026-07-31T23:59:59Z.

الأخطاء

تستخدم الأخطاء كائن error القياسي. قم بالتعامل معها استناداً إلى رمز الحالة (status) والخاصية code.

الحالةcodeالمعنى
400validation_errorحقل أو معامل استعلام (query parameter) غير صالح
400invalid_model_accessالنموذج المحدد في models غير مسموح به بموجب سياسة النماذج الخاصة بـ Workspace
400currency_retiredقيمة limitCurrency هي CNY؛ استخدم USD
401invalid_management_tokenالـ token مفقود أو غير صالح أو تم إلغاؤه
403organization_inactiveالـ Workspace غير نشط
404not_foundمفتاح API غير موجود في هذا الـ Workspace
409api_key_revokedلا يمكن تفعيل مفتاح تم إلغاؤه مجدداً؛ أنشئ مفتاحاً جديداً
429report_busyهناك عدد كبير جداً من تقارير الاستخدام أو الفوترة قيد التشغيل حالياً. أعد المحاولة بعد انقضاء الثواني المحددة في Retry-After

مثال

curl "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

الخطوات التالية

في هذه الصفحة