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

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

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

نظرة عامة

تتيح لك واجهة الإدارة استرجاع مجاميع رصيد المؤسسة وإدارة مفاتيح API الخاصة بالمؤسسة واسترجاع الاستخدام والفوترة لمفتاح محدد دون استخدام مفتاح استدلال عادي. استخدم رمز إدارة من صفحة الإعدادات في لوحة التحكم:

Authorization: Bearer mt-your-management-token

تختلف رموز الإدارة عن مفاتيح API الخاصة بالاستدلال. استخدم mt-... مع /v1/management/*، واستخدم sk-... مع واجهات الاستدلال مثل /v1/responses.

الواجهات المتاحة

نقطة النهاية	الطريقة	الوصف
`/v1/management/balance`	GET	يجلب مجاميع الرصيد الحالية للمؤسسة
`/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	يجلب تفاصيل الفوترة المجمعة لمفتاح محدد

عقد مرشحات الاستخدام

يدعم GET /v1/management/api-keys/{keyId}/usage معلمات الاستعلام التالية.

المعامل	النوع	القيم الافتراضية / القيود	الوصف
`page`	integer	الافتراضي `1`، الحد الأدنى `1`	رقم الصفحة بدءًا من 1
`limit`	integer	الافتراضي `50`، الحد الأدنى `1`، الحد الأقصى `100`	حجم الصفحة
`model`	string	أقصى طول `100`	اسم النموذج المطلوب
`modelVendor`	string	أقصى طول `100`	مزود النموذج العام
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	حد سفلي شامل؛ يقبل RFC3339 مع منطقة زمنية أو `YYYY-MM-DD`
`endDate`	string	-	حد علوي شامل؛ يقبل RFC3339 مع منطقة زمنية أو `YYYY-MM-DD`

إذا تم إرسال startDate و endDate معًا، فيجب أن يكون startDate أسبق من أو مساويًا لـ endDate.

عقد جسم مفتاح API

POST /v1/management/api-keys

الحقل	النوع	القيم الافتراضية / القيود	الوصف
`name`	string	مطلوب، الافتراضي `Default Key`، الطول `1-50`	اسم العرض؛ تتم إزالة المسافات من البداية والنهاية على الخادم
`limitAmount`	number \| null	الحد الأدنى `0`، الحد الأقصى للإدخال `1000000`	`null` أو الحذف = غير محدود، `0` = حصة صفرية. تُطبّع القيم الموجبة إلى حد مخزن لا يمكن أن يتجاوز ما يعادل `100000` دولارًا أمريكيًا.
`limitCurrency`	تعداد	افتراضي `USD`	USD فقط. إرسال `CNY` يُرجع `400 currency_retired`.
`models`	string[]	الافتراضي `[]`	قائمة اختيارية للنماذج المنطقية المسموح بها
`expiresAt`	string \| null	تاريخ ووقت RFC3339	`null` يعني عدم وجود انتهاء

PATCH /v1/management/api-keys/

الحقل	النوع	القيم الافتراضية / القيود	الوصف
`status`	enum	-	`active`, `inactive`, `revoked`
`name`	string	الطول `1-50`	اسم العرض بعد التحديث
`limitAmount`	number \| null	الحد الأدنى `0`، الحد الأقصى للإدخال `1000000`	`null` = غير محدود، `0` = حصة صفرية. تُطبّع القيم الموجبة إلى حد مخزن لا يمكن أن يتجاوز ما يعادل `100000` دولارًا أمريكيًا.
`limitCurrency`	تعداد	افتراضي `USD`	USD فقط. إرسال `CNY` يُرجع `400 currency_retired`.
`models`	string[]	-	قائمة النماذج المنطقية المسموح بها بعد التحديث
`expiresAt`	string \| null	تاريخ ووقت RFC3339	`null` يزيل تاريخ الانتهاء

يجب أن يتضمن طلب PATCH حقلًا واحدًا على الأقل.

حقول المبالغ المالية

تدعم حقول المبالغ المالية في طلبات واستجابات واجهة API للإدارة الدولار الأمريكي فقط.
القيمة الافتراضية لـ limitCurrency هي USD؛ ويؤدي إرسال CNY إلى إرجاع 400 currency_retired.

دلالات التقارير

يشير model إلى النموذج المطلوب الذي طلبه المستدعي.
يشير modelVendor إلى مزود النموذج العام، وليس المسار الفيزيائي المخفي.
تمثل scene مشهد الطلب العام المشتق من الواجهة أو نوع المهمة.

لا تكشف الاستجابات إلا حقول الفوترة والتقارير العامة. أما تفاصيل التوجيه الداخلي وبيانات المزود الفيزيائية فتبقى مخفية.

قد تتضمن عناصر /usage الحقل billing_transaction_id بعد اكتمال تسوية الطلب الأساسي. استخدم request_id + billing_transaction_id للمطابقة على مستوى الطلب.

ملاحظة حول ترقيم صفحات الفوترة

واجهة /usage تدعم ترقيم الصفحات. أما /billing فهي حاليًا واجهة تجميعية ولا تعيد بيانات ترقيم صفحات على نمط page / limit. وإذا كنت تحتاج إلى سجلات تفصيلية على مستوى الصفوف فاستعمل /usage.

مثال سريع

ابدأ بالتحقق من رصيد المؤسسة باستخدام رمز الإدارة الحالي:

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

ثم اعرض مفاتيح API المتاحة لرمز الإدارة نفسه:

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

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

الأساسيات

النص

الملفات والدفعات

الصور

الصوت والوقت الفعلي

الموسيقى

الفيديو والمواد

Worlds

3D

المهام غير المتزامنة

Gemini الأصلي

الإدارة

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

نظرة عامة

الواجهات المتاحة

عقد مرشحات الاستخدام

عقد جسم مفتاح API

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

حقول المبالغ المالية

دلالات التقارير

ملاحظة حول ترقيم صفحات الفوترة

مثال سريع

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

​نظرة عامة

​الواجهات المتاحة

​عقد مرشحات الاستخدام

​عقد جسم مفتاح API

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​حقول المبالغ المالية

​دلالات التقارير

​ملاحظة حول ترقيم صفحات الفوترة

​مثال سريع

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

نظرة عامة

الواجهات المتاحة

عقد مرشحات الاستخدام

عقد جسم مفتاح API

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

حقول المبالغ المالية

دلالات التقارير

ملاحظة حول ترقيم صفحات الفوترة

مثال سريع

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