دليل المنصة

API المنصة

اقرأ الكتالوج والأسعار ورصيدك واستخدامك من داخل الكود.

هذه الصفحة تغطي كل شيء عدا إرسال الطلبات النصية: ما هي النماذج المتاحة، وكم يتقاضى كل مزوّد، وكم أنفقت، وما المفاتيح التي تملكها. وكلها تُجيب بصيغة JSON على مضيف api نفسه الذي ترسل إليه طلبات الإكمال.

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

لا يغني أحدهما عن الآخر. فمفتاح API لا يستطيع قراءة رصيدك، ورمز الوصول لا يستطيع إرسال طلب إكمال.

بيانات الاعتماد	الشكل	ما الذي يفتحه
مفتاح API	`sk-...`	الاستدلال، وقائمة النماذج، وعدّاد استخدام ذلك المفتاح وحده.
رمز الوصول	من 29 إلى 32 حرفًا، بلا بادئة	حسابك: الرصيد، وإدارة المفاتيح، وسجلات الاستخدام.

كلاهما يُرسل في الترويسة نفسها، Authorization: Bearer متبوعة بالقيمة. ولا يُقرأ شيء غيرها. وبعض الأمثلة القديمة تضيف ترويسة New-Api-User، وهي متجاهَلة، ولا يوجد أي بديل احتياطي عبر ملفات تعريف الارتباط.

أرسل هذه الترويسة حتى حيث تستجيب نقطة النهاية بدونها. فالطلب الموجَّه إلى مسار خاص بالحساب ولا يحمل بيانات اعتماد قد يُواجَه بتحدٍّ أمني قبل أن يصل إلينا، والتحدي يُجيب بصيغة HTML بدل JSON.

افتح الإعدادات، وابحث عن وصول API ضمن قسم الأمان، ثم أنشئ رمزًا. يُعرض الرمز مرة واحدة فقط. ولا يمكن إنشاؤه إلا أثناء تسجيل دخولك، لذلك لا يستطيع أي سكربت توليد رمزه بنفسه.

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

تعامل معه كما تتعامل مع كلمة المرور. فهو قادر على إنفاق المال وإنشاء المفاتيح وقراءة سجلك. ألغِه من الشاشة نفسها متى لم يعد أي سكربت بحاجة إليه.

طلب عام واحد يُعيد كل النماذج، بأسعار محوّلة مسبقًا إلى الدولار لكل مليون رمز. بلا مفتاح وبلا تسجيل.

bash

curl https://api.unorouter.com/api/pricing/catalog

json

{
  "counts": { "models": 239, "free": 134, "paid": 105, "vendors": 50 },
  "first_free_model": "glm-5.3:free",
  "vendors": [{ "vendor_id": 4, "vendor_name": "Zhipu", "icon": "Zhipu.Color" }],
  "models": [
    {
      "model_name": "glm-5.3",
      "vendor": "Zhipu",
      "type": "text",
      "is_free": false,
      "online": true,
      "input_price": 0.05103,
      "output_price": 0.160382187,
      "original_input_price": 1.26,
      "original_output_price": 3.960054,
      "tags": "Text,Reasoning,Tools,Cache",
      "supported_endpoint_types": ["openai", "anthropic"],
      "uptime_24h": 99.965,
      "success_rate": 95,
      "avg_latency_ms": 11062
    }
  ]
}

يمثل input_price و output_price ما ستدفعه فعليًا اليوم لدى أرخص مزوّد يقدّم ذلك النموذج حاليًا. أما original_input_price و original_output_price فهما سعر القائمة لدى المورّد نفسه، والفارق بين الاثنين هو الخصم. ويشير is_free إلى النماذج التي لا تتقاضى شيئًا أبدًا، ويشير online إلى النماذج التي لديها مزوّد فعّال في هذه اللحظة.

وهناك نقطتان أصغر: /api/pricing/counts تُعيد الإجماليات فقط وهي خفيفة بما يكفي للاستعلام المتكرر، و/api/pricing/vendors تُعيد قائمة الموردين. أما نقطة النهاية الأقدم /api/pricing فتُعيد النسب الخام بدل الدولارات وحجمها أكبر بعدة أضعاف.

معظم النماذج يقدّمها عدة مزوّدين بأسعار مختلفة. اطلب نموذجًا واحدًا لترى هؤلاء المزوّدين جميعًا.

bash

curl "https://api.unorouter.com/api/pricing/catalog/model?model=glm-5.3"

json

{
  "model_name": "glm-5.3",
  "model_ratio": 0.63,
  "completion_ratio": 3.1429,
  "cache_ratio": 0.1857,
  "input_price": 0.05103,
  "output_price": 0.160382187,
  "grid_min_ratio": 0.0405,
  "auto_chain": ["a7-bbgt-2846-glm-5.3", "a7-kkl-3731-glm-5.3", "a7-4069-glm-5.3"],
  "group_ratio": {
    "a7-bbgt-2846-glm-5.3": 0.0405,
    "a7-kkl-3731-glm-5.3": 0.0911,
    "a7-4069-glm-5.3": 0.1214
  },
  "enable_groups": ["a7-bbgt-2846-glm-5.3", "a7-kkl-3731-glm-5.3"]
}

يمثل auto_chain الترتيب الذي يجربهم به التوجيه، من الأرخص فالأغلى. ويُعطي group_ratio معامل كل مزوّد، ومنه يُشتق السعر:

text

input  $/1M = model_ratio * 2 * group_ratio
output $/1M = input * completion_ratio
cached $/1M = input * cache_ratio

glm-5.3 on a7-bbgt-2846: 0.63 * 2 * 0.0405 = $0.05103 / 1M in
                          0.05103 * 3.1429  = $0.16038 / 1M out

أسماء المجموعات هذه هي نفسها التي تثبّت المفتاح عليها، انظر تثبيت المجموعات

القائمة المتوافقة مع OpenAI هي ما يستدعيه معظم العملاء عند الضغط على الاتصال. وهي تحتاج إلى مفتاح API.

bash

curl https://api.unorouter.com/v1/models \
  -H "Authorization: Bearer $UNOROUTER_API_KEY"

تُعيد فقط ما يُسمح لذلك المفتاح باستخدامه فعليًا، لذا يرى مفتاح الطبقة المجانية نماذج أقل مما يراه مفتاح مموَّل. وكل عنصر يحمل أيضًا context_length و max_output_tokens، وهما غير متوفرين في OpenAI العادي.

المسار هو /v1/models. وإذا حذفت /v1 وصلت إلى صفحة ويب بدل الواجهة البرمجية، وهو ما يُبلغ عنه العملاء كخطأ في تحليل JSON بسبب doctype غير متوقع.

استدعاء واحد يُعيد حسابك، بما في ذلك ما تبقّى لديك للإنفاق.

bash

curl https://api.unorouter.com/api/user/self \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN"

json

{
  "success": true,
  "message": "",
  "data": {
    "id": 12345,
    "username": "you",
    "group": "default",
    "quota": 265000,
    "used_quota": 4231900,
    "request_count": 1884,
    "aff_code": "ABC123"
  }
}

المبالغ محسوبة بوحدات quota لا بالدولارات. وكل 500,000 وحدة تساوي دولارًا أمريكيًا واحدًا، فالرصيد أعلاه يساوي $0.53. اقسم على 500,000 لعرض المبلغ نقدًا.

يمثل quota ما يمكنك إنفاقه بعد. أما used_quota و request_count فهما إجماليان تراكميان لا يتناقصان أبدًا، ولذلك ليس used_quota فرقًا بين أي شيء ورصيدك.

اسرد مفاتيحك، ثم اكشف واحدًا منها بمعرّفه.

bash

curl "https://api.unorouter.com/api/token/?p=1&page_size=20" \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN"

curl -X POST https://api.unorouter.com/api/token/42/key \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN"

السرد يُخفي قيمة كل مفتاح، ولهذا يكون الكشف استدعاءً منفصلًا. وهذا الاستدعاء محدود المعدل ومسجَّل في سجل التدقيق الخاص بك.

إنشاء مفتاح يعيد success لكنه لا يعيد المفتاح نفسه. أنشئه، ثم اعرض القائمة للعثور على id الخاص به، ثم اكشفه. تحديث المفتاح يعيد الكائن بعد التحديث، لكن أرسل الكائن كاملاً: لا ينجو من الحذف سوى cross_group_retry و group_mapping و auto_groups، وأي حقل آخر تحذفه تتم إعادة كتابته فارغاً.

سجل طلباتك مقسّم إلى صفحات وقابل للتصفية.

bash

curl -G https://api.unorouter.com/api/log/self \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN" \
  -d p=1 \
  -d page_size=100 \
  -d type=2 \
  -d start_timestamp=1789344000 \
  -d model_name=glm-5.3

المعامل	المعنى
`type`	1 شحن رصيد، 2 استهلاك، 3 إدارة، 5 خطأ، 6 استرداد، 7 تسجيل دخول. احذفه لتشمل كل شيء.
`start_timestamp, end_timestamp`	ثوانٍ بتوقيت يونكس. ولا يجوز أن تتجاوز المسافة بينهما عشر سنوات.
`model_name, token_name, group`	التضييق على نموذج واحد أو مفتاح واحد أو مجموعة مزوّد واحدة.
`request_id, upstream_request_id`	العثور على طلب واحد، بمعرّفنا أو بمعرّف المزوّد.

أضف p و page_size لتقسيم الصفحات، وحجم الصفحة محدود بـ 100. وهناك نقطة نهاية شقيقة، /api/log/self/stat، تُعيد الإجماليات فقط للمرشحات نفسها: الإنفاق، وعدد الطلبات في الدقيقة، وعدد الرموز في الدقيقة.

لقراءة الرصيد المتبقي لمفتاح واحد دون رمز وصول، تحقق من الهوية بالمفتاح نفسه:

bash

curl https://api.unorouter.com/api/usage/token/ \
  -H "Authorization: Bearer $UNOROUTER_API_KEY"

json

{
  "object": "token_usage",
  "name": "SillyTavern",
  "total_granted": 500000,
  "total_used": 231900,
  "total_available": 268100,
  "unlimited_quota": false,
  "model_limits_enabled": false,
  "expires_at": 0
}

نقاط نهاية الحساب تغلّف حمولتها. والمقسّمة إلى صفحات تغلّفها مرتين.

json

{ "success": true, "message": "", "data": { ... } }

{ "success": true, "message": "", "data": {
    "page": 1, "page_size": 20, "total": 137, "items": [ ... ]
} }

نقاط نهاية الكتالوج العامة هي الاستثناء، فهي تُعيد كائنها مباشرة دون أي غلاف.

معظم حالات الفشل تُجيب رغم ذلك بـ HTTP 200 مع ضبط success على false ورسالة تشرح السبب. تحقق من هذا الحقل بدل رمز الحالة.

المصادقة هي الاستثناء، فهي تُجيب برمز حالة حقيقي: 401 مع AUTH_UNAUTHORIZED لبيانات اعتماد خاطئة، و AUTH_TOKEN_EXPIRED لبيانات منتهية الصلاحية، و AUTH_SESSION_REVOKED بعد تسجيل الخروج، و 403 مع AUTH_INSUFFICIENT_PRIVILEGE عندما لا يُسمح للحساب باستدعاء ذلك المسار.

API المنصة

ما الذي تغطيه هذه الصفحة

نوعان من بيانات الاعتماد

الحصول على رمز وصول

كتالوج النماذج

أسعار نموذج واحد لدى كل مزوّد

سرد النماذج باستخدام مفتاح

رصيدك

إدارة مفاتيح API

الاستخدام والسجلات

شكل الاستجابة والأخطاء