فهم ترويسات HTTP ونقاط نهاية البروتوكول الأصلية في TokenLab

نقاط نهاية البروتوكول تحدد مخططات حمولة البيانات

لا يستخدم TokenLab ترويسات تلميح التنسيق الديناميكية (مثل وسوم format-hint الخاصة) للإشارة إلى مخططات الاستجابة أثناء التشغيل (runtime). بدلاً من ذلك، تخضع هياكل حمولة البيانات (payload) بشكل صارم لنقطة النهاية المطلوبة. يتطلب تحليل استجابات العميل توجيه الطلبات إلى نقطة نهاية البروتوكول الأصلية المستهدفة بدلاً من فحص ترويسات الاستجابة لمعرفة أنواع الحمولة:

• Chat Completions (/v1/chat/completions): يستخدم مخططات متوافقة مع OpenAI تُرجع choices، وmessage.content، وكتلة usage (prompt_tokens، وcompletion_tokens، وtotal_tokens).
• Responses (/v1/responses): يلتزم بتنسيق OpenAI Responses API للمهام في الخلفية، وأدوات الخادم، وأحداث الاستجابة.
• Anthropic Messages (/v1/messages): يتفاعل مع نماذج Anthropic Claude باستخدام مخطط Anthropic الأصلي (كتل content، وthinking، وoutput_tokens). عند تكوين Anthropic SDK، عيّن عنوان URL الأساسي (base URL) إلى https://api.tokenlab.sh بدون البادئة /v1.
• Gemini (/v1beta/models/:model:generateContent): يقبل مخططات Gemini الأصلية (contents، وparts) ويُرجع كائنات مرشحة قياسية خاصة بـ Gemini REST.

قبل توجيه طلب إلى نموذج ما، تحقق من البروتوكولات التي يقبلها عن طريق استدعاء الحصول على نموذج (GET /v1/models/{model}) أو مراجعة كتالوج النماذج. افحص قائمة tokenlab.accepted_request_formats في الاستجابة. راجع دليل تنسيقات واجهة برمجة التطبيقات للاطلاع على القواعد الشاملة لتعيين نقاط النهاية.

ترويسات الطلب الموثقة

تتطلب جميع الاستدعاءات القياسية لنقاط نهاية TokenLab ترويسات طلب HTTP محددة:

• Authorization: تُمرر بيانات الاعتماد كرمز حامل (bearer token) (Authorization: Bearer $TOKENLAB_API_KEY). تتطلب نقاط نهاية الإدارة رمز إدارة (Authorization: Bearer mt-...).
• Content-Type: يجب أن تكون application/json لطلبات POST التي تحتوي على نصوص بتنسيق JSON.

ترويسات الاستجابة الموثقة

يُرجع TokenLab ترويسات HTTP قياسية ومخصصة لحدود المعدل، وتسوية الفوترة، وإدارة المهام غير المتزامنة:

ترويسات الحد من المعدل

عندما يتجاوز الطلب حدود فئة الحساب، يُرجع TokenLab حالة HTTP 429 rate_limit_exceeded مصحوبة بترويستين:

• Retry-After: تحدد فترة الانتظار المطلوبة بالثواني قبل إعادة محاولة الاستدعاء.
• X-RateLimit-Limit: تُبلغ عن الحد الفعلي لعدد الطلبات في الدقيقة لفئتك المصادق عليها.

استخدم دائمًا قيمة ترويسة Retry-After للتعامل مع عمليات إعادة المحاولة بدلاً من تحديد فترات انتظار ثابتة برمجيًا. تتوفر تفاصيل إضافية حول معالجة الاسترداد في دليل حدود المعدل.

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

بالنسبة للتفاعلات غير المتدفقة (non-streaming) وغير المتزامنة، يوفّر TokenLab ترويسات تعريف لتتبع الرسوم والعمليات في الخلفية:

• X-Billing-Transaction-ID: تُعاد عندما تتم تسوية الفوترة قبل إرسال استجابة HTTP. تتضمن نقاط النهاية غير المتدفقة المتوافقة مع OpenAI المعرّف billing_transaction_id داخل نص JSON، ولكن نقاط نهاية Gemini ونقاط النهاية بالتنسيق الأصلي تعرضه عبر هذه الترويسة. قد تتم تسوية الاستدعاءات المتدفقة بعد إغلاق الاتصال؛ وفي حال غيابه، يمكن استرداد المعرّف من سجلات استخدام مساحة العمل. راجع تدفقات عمل التسوية في دليل الفوترة والتسعير.
• X-Task-ID: تُعاد في ترويسات الاستجابة عند إنشاء مهام غير متزامنة لإنشاء الفيديو أو الموسيقى أو النماذج ثلاثية الأبعاد (3D) أو الصور القائمة على المهام. وتوفر معرّف ارتباط على مستوى الترويسة يقابل id الخاص بالمهمة. راجع دليل السجلات واستكشاف الأخطاء وإصلاحها للاطلاع على معايير تسجيل السجلات.

التنفيذ العملي: التقاط الترويسات وإعادة المحاولة عند الخطأ 429

يوضح مثال Python التالي كيفية إرسال طلب إلى نقطة نهاية Chat Completions، وفحص معرّفات المعاملات، والتعامل مع ترويسات Retry-After أثناء تجاوز حدود المعدل:

import os
import time
import requests

API_KEY = os.environ["TOKENLAB_API_KEY"]
ENDPOINT = "https://api.tokenlab.sh/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Summarize system status."}]
}

max_attempts = 3
for attempt in range(max_attempts):
    response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)

    if response.status_code == 200:
        # Check for billing transaction header on settled non-streaming calls
        billing_id = response.headers.get("X-Billing-Transaction-ID")
        data = response.json()
        print(f"Settled Transaction ID: {billing_id}")
        print(data["choices"][0]["message"]["content"])
        break

    elif response.status_code == 429:
        retry_after = response.headers.get("Retry-After")
        limit = response.headers.get("X-RateLimit-Limit")
        wait_seconds = float(retry_after) if retry_after else 2 ** attempt
        print(f"Rate limit reached ({limit} req/min). Retrying in {wait_seconds}s...")
        time.sleep(wait_seconds)
    else:
        response.raise_for_status()

ممارسات تسجيل السجلات وقابلية الملاحظة

عند إعداد مراقبة الطلبات، سجّل معرّفات التتبع العامة المُرجعة في الترويسات والحمولات لتسوية السجلات دون الاحتفاظ بمطالبات المستخدم (prompts) أو بيانات اعتماده:

• احتفظ بـ request_id وX-Billing-Transaction-ID وX-Task-ID إلى جانب رموز الحالة وأوقات استجابة الطلبات.
• احجب دائمًا ترويسات Authorization، ومفاتيح API الأولية، وعناوين URL الموقعة الخاصة من مسارات القياس عن بُعد (telemetry pipelines).
• لإجراء التسوية المالية من جانب الخادم، استعلم عن GET /v1/management/api-keys/{keyId}/usage بدلاً من كشط صفحات لوحة التحكم أو تقدير الإجماليات بالاعتماد على عدادات الرموز الأولية وحدها.