اختيار مستوى تسليم TokenLab: Auto أو Verified أو Official

قد يفشل الطلب مع ظهور رمز الخطأ 503 على الرغم من أن معرف النموذج (model ID) صالح تماماً، وغالباً ما يكون السبب هو مستوى التسليم (delivery tier) الذي قمت بتحديده. في خط أنابيب العمليات الخاص بنا، واجهنا هذه المشكلة عندما فرضنا خياراً واحداً على نموذج لم يكن يوفره. يشرح هذا الدليل خيارات مستوى التسليم الثلاثة، وترتيب تطبيق الإعدادات، وما يعنيه كل خيار بالنسبة لفاتورتك. جميع الحقائق الواردة أدناه مستمدة من وثائق TokenLab وواجهة برمجة تطبيقات (API) النماذج المباشرة، كما تمت ملاحظتها بتاريخ 2026-10-03.

نقاط رئيسية

• يحتوي مستوى التسليم على ثلاث قيم: auto و verified و official.
• يتجاوز ترويسة الطلب (request header) إعداد مفتاح API، والذي بدوره يتجاوز الإعداد الافتراضي لمساحة العمل (Workspace).
• إذا لم يكن الخيار المطلوب متاحاً، فستتلقى الخطأ 503 delivery_tier_unavailable. عندما تكون قيمة retryable هي false، لا تقم بإعادة إرسال نفس الطلب.
• أنت تدفع مرة واحدة فقط، مقابل الخيار الذي أكمل الطلب.
• تحقق من GET /v1/models/{model} قبل تثبيت مستوى معين. هذا الرابط عام ولا يحتاج إلى مفتاح.

خيارات مستوى التسليم الثلاثة

يحدد مرجع API (كما تمت ملاحظته بتاريخ 2026-10-03) ثلاثة خيارات:

• Auto: يستخدم TokenLab Verified عند توفره، ثم Official إذا لزم الأمر. أنت تدفع مقابل الخيار الذي يكمل طلبك.
• TokenLab Verified: هو تسليم تم التحقق منه بواسطة TokenLab. تُطبق أسعار TokenLab.
• Official: يعتمد على السعر العام لصانع النموذج. السعر المعروض على TokenLab هو ما تدفعه.

تقبل طلبات التوليد الترويسة X-TokenLab-Delivery-Policy: auto | verified | official. تؤدي قيمة الترويسة غير الصالحة إلى إرجاع 400.

أي إعداد يتم تطبيقه أولاً

يمكن تعيين مستوى التسليم في ثلاثة أماكن. الترتيب الموثق هو:

1. ترويسة الطلب (request header).
2. إعداد مفتاح API.
3. الإعداد الافتراضي لمساحة العمل (Workspace).

تتجاوز الترويسة المفتاح، ويتجاوز المفتاح مساحة العمل. الاستثناء هو الجلسات في الوقت الفعلي (Realtime sessions): فهي تستخدم إعداد مفتاح API أو مساحة العمل ولا تقبل التجاوز عبر سلسلة الاستعلام (query-string).

تعيين مستوى التسليم في طلب

إليك استدعاء Chat Completions يقوم بتثبيت تسليم Official. معرف النموذج claude-sonnet-5 مدرج في واجهة برمجة تطبيقات النماذج المباشرة مع توفر كلا الخيارين. راجع صفحة النموذج.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: official" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

تعمل نفس الترويسة على نقطة نهاية Anthropic Messages. بالنسبة لـ /v1/messages، يمكن أن تكون ترويسة المفتاح هي x-api-key، والتي يشير مرجع API إلى أن Anthropic Messages تقبلها.

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: $TOKENLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: verified" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

تعيين مستوى التسليم على مفتاح API

لجعل مستوى التسليم افتراضياً لمفتاح واحد، استخدم Management API مع رمز إدارة (mt-...). توثق صفحات إنشاء مفتاح API وتحديث مفتاح API (كلاهما تمت ملاحظتهما بتاريخ 2026-10-03) حقلاً باسم deliveryPolicy. قيم هذا الحقل هي auto أو verified أو official أو null. القيمة null ترث سياسة مساحة العمل.

يتبع هذا الرسم التخطيطي شكل PATCH الموثق. معرف المفتاح هو قيمة مثال الوثائق.

curl -X PATCH "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456" \
  -H "Authorization: Bearer mt-your-management-token" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryPolicy": "verified"
  }'

يتطلب التحديث حقلاً واحداً على الأقل، لذا فإن هذا النص الأساسي صالح بمفرده. تبلغ الاستجابات عن الإعداد باسم delivery_policy، حيث تعني null أن المفتاح يرث الإعداد الافتراضي لمساحة العمل. تقبل نقطة نهاية الإنشاء نفس حقل deliveryPolicy في نص الطلب الخاص بها. حذف الحقل عند الإنشاء يتوافق مع وراثة null الموثقة، كما يظهر مثال استجابة الإنشاء delivery_policy: null.

عندما يكون الخيار المطلوب غير متاح

إذا لم يكن الخيار الذي تطلبه متاحاً، تُرجع TokenLab الخطأ 503 delivery_tier_unavailable ومعرف طلب. يشرح دليل معالجة الأخطاء (تمت ملاحظته بتاريخ 2026-10-03) كيفية قراءة retryable.

حالة 5xx لا تعني دائماً انقطاعاً مؤقتاً. عندما لا تتوفر العملية المحددة في ذلك المستوى، تكون قيمة retryable هي false ويتم حذف retry_after. لا تكرر نفس الطلب دون تغيير. بدلاً من ذلك:

1. اقرأ code و retryable، وليس message القابل للقراءة البشرية.
2. احفظ معرف الطلب (Request ID) من ترويسات الاستجابة.
3. تحقق من توفر تسليم النموذج باستخدام GET /v1/models قبل اختيار نموذج أو مستوى آخر.

يحذر الدليل من أن أسماء النماذج المتشابهة لا تثبت التوفر. يجب على العميل التفرع بناءً على code، وإعادة محاولة طلب 5xx فقط عندما تكون retryable هي true، مع احترام retry_after وتحديد سقف للمحاولات.

التحقق من الخيارات التي يمتلكها النموذج

تُبلغ نقطة نهاية النموذج عن delivery availability by option. هذه القيم تأتي من واجهة برمجة تطبيقات النماذج المباشرة، كما تمت ملاحظتها بتاريخ 2026-10-03:

معرف النموذج	Verified	Official	صفحة النموذج
claude-sonnet-5	true	true	/models/claude-5/claude-sonnet-5
gpt-5.6-terra	true	true	/models/gpt-5-6/gpt-5.6-terra
deepseek-v4-flash	false	true	/models/deepseek-v4/deepseek-v4-flash

على سبيل المثال، تثبيت verified على deepseek-v4-flash هو نوع الطلب الذي سيواجه delivery_tier_unavailable، لأن واجهة برمجة التطبيقات لا تبلغ عن أي توفر لـ Verified اليوم. يظل خيارا Official و Auto صالحين هناك.

تحقق من أي نموذج بنفسك:

curl "https://api.tokenlab.sh/v1/models/deepseek-v4-flash"

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

كيف يؤثر الاختيار على ما تدفعه

يقول دليل الفوترة (تمت ملاحظته بتاريخ 2026-10-03) إن كل طلب مكتمل يتم محاسبته مرة واحدة، مقابل الخيار الذي أنتج النتيجة:

• TokenLab Verified يستخدم أسعار TokenLab العامة.
• Official يستخدم طبقة السعر الرسمية بناءً على السعر العام لصانع النموذج.
• Auto يحاسب على الخيار الذي يكمل الطلب.

بالنسبة للتوليد المدفوع، تعرض وحدة التحكم (Console) حداً أقصى تقديرياً قبل التأكيد، ويعرض الاستخدام (Usage) الرسوم النهائية. يتم تحرير أي مبلغ محجوز غير مستخدم. في صفحة النماذج، تعني الشرطة في عمود سعر TokenLab عدم توفر عرض Verified حالياً. هذا لا يعني أنه مجاني.

لا توثق الوثائق وجود فجوة سعرية ثابتة بين Verified و Official، لذا لن ندعي وجود واحدة. بالنسبة لسعر TokenLab المباشر على claude-sonnet-5، تدرج واجهة برمجة تطبيقات النماذج المدخلات بـ 0.9 دولار والمخرجات بـ 4.5 دولار لكل مليون رمز (تم تحديث الأسعار في 2026-10-02). كتقدير، 100,000 رمز مدخلات زائد 10,000 رمز مخرجات يساوي 0.09 + 0.045 = 0.135 دولار. هذا الرقم يستخدم سعر TokenLab المدرج فقط. اقرأ السعر الرسمي على صفحة النموذج قبل المقارنة.

دليل قرار سريع

• اجعل Auto هو الافتراضي عندما تريد إكمال الطلب ويمكنك قبول أي من طبقتي السعر.
• ثبّت Verified عندما تحتاج إلى أسعار TokenLab ويكون النموذج يبلغ عن verified: true.
• ثبّت Official عندما تحتاج إلى أساس السعر العام لصانع النموذج، أو عندما لا يكون لدى النموذج أي توفر لـ Verified.
• عيّن الافتراضي للمفتاح للعاملين الذين يحتاجون دائماً إلى نفس المستوى، واستخدم الترويسة للاستثناءات الفردية.

قبل التثبيت، اقرأ GET /v1/models/{model}. قم بإجراء اختبار صغير وتأكد من الرسوم في الاستخدام.

الخطوة التالية: إنشاء مفتاح بسياسة تسليم

أنشئ مفتاح API في وحدة التحكم، أو استدعِ POST /v1/management/api-keys باستخدام رمز إدارة وعيّن deliveryPolicy في النص الأساسي، كما هو موضح في صفحة إنشاء مفتاح API. ثم أرسل طلباً صغيراً واحداً مع الترويسة من أعلاه وتحقق من الرسوم في الاستخدام.

الأسئلة الشائعة

أي إعداد يفوز إذا تعارضت الترويسة ومفتاح API ومساحة العمل؟

تفوز ترويسة الطلب. يتجاوز إعداد مفتاح API الإعداد الافتراضي لمساحة العمل. تتخطى الجلسات في الوقت الفعلي الترويسة وتستخدم إعداد المفتاح أو مساحة العمل.

لماذا حصلت على 503 delivery_tier_unavailable، وهل يجب أن أعيد المحاولة؟

المستوى الذي طلبته لا يحتوي على توفر لتلك العملية. اقرأ retryable: عندما تكون false، لا تقم بإعادة إرسال نفس الطلب. تحقق من التوفر باستخدام GET /v1/models وقم بتغيير المستوى أو النموذج.

هل يكلف Official أكثر من TokenLab Verified؟

لا تنص الوثائق على فرق ثابت. يستخدم Verified أسعار TokenLab العامة، ويستخدم Official أساس السعر العام لصانع النموذج. قارن بين الاثنين في صفحة النموذج وتأكد من الرسوم النهائية في الاستخدام.

كيف يمكنني معرفة خيارات التسليم التي يدعمها النموذج؟

استدعِ GET /v1/models/{model}، والذي لا يحتاج إلى مفتاح. اليوم تبلغ claude-sonnet-5 و gpt-5.6-terra عن Verified و Official، بينما تبلغ deepseek-v4-flash عن Official فقط.

هل يمكنني تعيين خيار تسليم للجلسات في الوقت الفعلي؟

نعم، من خلال إعداد مفتاح API أو مساحة العمل. لا تقبل الجلسات في الوقت الفعلي تجاوزاً عبر سلسلة الاستعلام.

أنشئ مفتاح API الخاص بـ TokenLab في وحدة التحكم