الإدارة
واجهة برمجة تطبيقات الإدارة
التحقق من أرصدة 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/balance | GET | الحصول على رصيد Workspace |
/v1/management/api-keys | GET | سرد مفاتيح API |
/v1/management/api-keys | POST | إنشاء مفتاح API |
/v1/management/api-keys/{keyId} | PATCH | تغيير اسمه أو الحد الأقصى أو النماذج أو تاريخ انتهاء الصلاحية أو الحالة |
/v1/management/api-keys/{keyId}/usage | GET | الحصول على سجلات الاستخدام الفردية |
/v1/management/api-keys/{keyId}/billing | GET | الحصول على ملخص الفوترة |
مفاتيح 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 | المعنى |
|---|---|---|
| 400 | validation_error | حقل أو معامل استعلام (query parameter) غير صالح |
| 400 | invalid_model_access | النموذج المحدد في models غير مسموح به بموجب سياسة النماذج الخاصة بـ Workspace |
| 400 | currency_retired | قيمة limitCurrency هي CNY؛ استخدم USD |
| 401 | invalid_management_token | الـ token مفقود أو غير صالح أو تم إلغاؤه |
| 403 | organization_inactive | الـ Workspace غير نشط |
| 404 | not_found | مفتاح API غير موجود في هذا الـ Workspace |
| 409 | api_key_revoked | لا يمكن تفعيل مفتاح تم إلغاؤه مجدداً؛ أنشئ مفتاحاً جديداً |
| 429 | report_busy | هناك عدد كبير جداً من تقارير الاستخدام أو الفوترة قيد التشغيل حالياً. أعد المحاولة بعد انقضاء الثواني المحددة في Retry-After |
مثال
curl "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"