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

نظرة عامةCopy Anchor Link

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

أنشئ رمز إدارة من Dashboard → API → Management Tokens:

Authorization: Bearer mt-your-management-token

الواجهات المتاحةCopy Anchor Link

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

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

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

عقد جسم مفتاح APICopy Anchor Link

POST /v1/management/api-keysCopy Anchor Link

PATCH /v1/management/api-keys/{keyId}Copy Anchor Link

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

حقول المبالغ الماليةCopy Anchor Link

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

دلالات التقاريرCopy Anchor Link

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

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

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

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

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

مثال سريعCopy Anchor Link

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

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",
      "delivery_policy": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

الخطوات التاليةCopy Anchor Link

• الحصول على رصيد المؤسسة
• عرض مفاتيح API
• إنشاء مفتاح API
• تحديث مفتاح API
• جلب استخدام مفتاح API
• جلب فوترة مفتاح API