✨ واجهة برمجة تطبيقات متعددة الصيغ

نظرة عامة

تعرض TokenLab أربع واجهات بروتوكول بمفتاح API واحد: Chat Completions وResponses وAnthropic Messages وGemini الأصلي. لا يتوفر المدخل الأصلي إلا عندما يعلن النموذج عن الصيغة وتوجد له قناة upstream من البروتوكول نفسه؛ ولا يعود أي مدخل أصلي إلى Chat Completions. يمكن لمدخل Chat فقط التحويل باتجاه واحد إلى بروتوكول آخر متوافق.

صيغة OpenAI

/v1/chat/completions صيغة قياسية، أوسع توافق

Responses

/v1/responses دورة حياة وأحداث Responses الأصلية

صيغة Anthropic

/v1/messages تفكير موسّع، ميزات Claude الأصلية

صيغة Gemini

/v1beta/models/:model:generateContent تكامل مع نظام Google البيئي

لماذا الصيغ المتعددة؟

الميزة	الوصف
SDK أصلي للبروتوكول	استخدم SDK الأصلي فقط مع النماذج التي تعلن عن هذه الصيغة؛ ويظل Chat المسار المحمول الأوسع
ميزات أصلية	الوصول إلى قدرات خاصة بكل صيغة
ترحيل سهل	الانتقال من واجهات API الرسمية بتغيير عنوان الأساس فقط
فوترة واحدة	حساب واحد، مفتاح API واحد، جميع الصيغ

مقارنة الصيغ

الميزة	OpenAI	Anthropic	Gemini
نقطة النهاية	`/v1/chat/completions`	`/v1/messages`	`/v1beta/models/:model:generateContent`
رأس المصادقة	`Authorization: Bearer`	`x-api-key`	`Authorization: Bearer`
موجه النظام	داخل مصفوفة `messages`	حقل `system` منفصل	داخل `systemInstruction`
التفكير الموسّع	❌	✅	❌
البث	✅ SSE	✅ SSE	✅ SSE
استدعاء الأدوات	✅	✅	✅
الرؤية	✅	✅	✅

صيغة OpenAI

استخدم مسار التوافق هذا للتكاملات الحالية مع OpenAI SDK وتدفّقات الدردشة أو التضمين المحمولة. بالنسبة لسلوك Claude أو Gemini الأصلي، استخدم تنسيق Anthropic أو Gemini أدناه.

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1"
)

# Portable chat works across many models
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # Claude via OpenAI format
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

مناسب لـ:

الاستخدام العام
التكاملات القائمة مع OpenAI SDK
أقصى درجات التوافق

صيغة Anthropic

واجهة Anthropic Messages الأصلية. مطلوبة لميزات Claude الخاصة مثل التفكير الموسّع.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh"  # No /v1 suffix!
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a helpful assistant.",  # Separate system field
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

التفكير الموسّع (Claude Opus 4.6)

متاح فقط في صيغة Anthropic:

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this complex problem..."}]
)

# Access thinking process
for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Answer: {block.text}")

مناسب لـ:

الميزات الخاصة بـ Claude
وضع التفكير الموسّع
مستخدمي Anthropic SDK الأصليين

صيغة Gemini

صيغة Google Gemini الأصلية لتكامل نظام Google البيئي.

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Hello!"}]
    }],
    "systemInstruction": {
      "parts": [{"text": "You are a helpful assistant."}]
    }
  }'

البث

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a story"}]}]
  }'

مناسب لـ:

تكاملات Google Cloud
مشروعات قائمة باستخدام Gemini SDK
ميزات Gemini الأصلية

Gemini Files و Cache: يدعم مسار Gemini الأصلي /upload/v1beta/files و /v1beta/files و /v1beta/files:register و /v1beta/cachedContents. تستخدم Files قنوات upstream متوافقة مع Gemini File API؛ ويمكن أيضًا توجيه موارد Cache الصريحة عبر قنوات Vertex AI. الموارد التي يتم إنشاؤها عبر TokenLab ترتبط بالقناة/key نفسها في upstream لاستخدامها لاحقًا في استدعاءات generateContent.

حدود توافق الأدوات

يمكن تحويل أدوات الدوال من مدخل Chat باتجاه واحد عندما يستطيع المسار الهدف تمثيل دورة الأداة كاملة. أما أدوات المزوّد الأصلية فيجب أن تبقى على مسارها الأصلي:

أدوات OpenAI Responses المستضافة والأصلية مثل tool_search وweb_search وfile_search وcode_interpreter وMCP وshell/apply_patch وأدوات computer-use تتطلب /v1/responses.
أدوات Anthropic server/native مثل web_search_* وweb_fetch_* وcode_execution_* وtool_search_* وbash وcomputer-use وtext-editor تتطلب /v1/messages.
أدوات Gemini المدمجة مثل googleSearch وcodeExecution وurlContext وcomputerUse وحقول tools المشابهة تتطلب /v1beta.

لا تخفض TokenLab طلبات البروتوكول الأصلي إلى Chat Completions. تُمرر الحقول غير المعروفة وتركيبات الأدوات بأفضل جهد، ويحدد upstream المختار ما إذا كانت مدعومة.

اختيار الصيغة المناسبة

أدلة الترحيل

من واجهة OpenAI الرسمية

# Before (OpenAI)
client = OpenAI(api_key="sk-openai-key")

# After (TokenLab)
client = OpenAI(
    api_key="sk-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1"  # Add this line
)
# That's it! Same code works

من واجهة Anthropic الرسمية

# Before (Anthropic)
client = Anthropic(api_key="sk-ant-key")

# After (TokenLab)
client = Anthropic(
    api_key="sk-tokenlab-key",
    base_url="https://api.tokenlab.sh"  # Add this line (no /v1!)
)

من Google AI Studio

# Before (Google)
import google.generativeai as genai
genai.configure(api_key="google-api-key")

# After (TokenLab) - Use REST API
import requests

response = requests.post(
    "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent",
    headers={"Authorization": "Bearer sk-tokenlab-key"},
    json={"contents": [{"parts": [{"text": "Hello"}]}]}
)

توافق Chat المحمول

استخدم /v1/chat/completions عندما يحتاج عميل واحد إلى الوصول إلى نماذج تدعمها بروتوكولات upstream مختلفة. يمكن لطلب Chat المحمول أن يُترجم باتجاه واحد إلى Responses أو Messages أو Gemini عندما يمكن تمثيله بالكامل. لا تُحوَّل طلبات Responses أو Messages أو Gemini الأصلية إلى Chat، ولا يعني اسم النموذج أو المزوّد أن البروتوكول الأصلي متاح.

حدود Responses وGemini

تشمل واجهة Responses الحالية الإنشاء والضغط والاسترجاع والحذف وSSE. يعمل background عبر HTTP فقط. يقبل WebSocket أحداث response.create فقط؛ التدفق ضمني، وbackground وresponse.cancel غير مدعومين على هذا النقل. الحذف ليس إلغاءً. في Gemini، أسماء ProtoJSON بصيغة lowerCamelCase وأسماء proto الأصلية بصيغة snake_case رسمية معًا، وتُحفظ حتى في الطلبات المختلطة. تشمل الواجهة الحالية list/get models وgenerateContent وstreamGenerateContent وcountTokens وembedContent وbatchEmbedContents؛ ولا تشمل Interactions أو Live. تُمرر الحقول غير المعروفة بأفضل جهد، ويقرر upstream ما إذا كانت مدعومة.

البدء

الأدلة الأساسية

أدلة الوسائط

✨ واجهة برمجة تطبيقات متعددة الصيغ

نظرة عامة

صيغة OpenAI

Responses

صيغة Anthropic

صيغة Gemini

لماذا الصيغ المتعددة؟

مقارنة الصيغ

صيغة OpenAI

صيغة Anthropic

التفكير الموسّع (Claude Opus 4.6)

صيغة Gemini

البث

حدود توافق الأدوات

اختيار الصيغة المناسبة

أدلة الترحيل

من واجهة OpenAI الرسمية

من واجهة Anthropic الرسمية

من Google AI Studio

توافق Chat المحمول

حدود Responses وGemini

​نظرة عامة

صيغة OpenAI

Responses

صيغة Anthropic

صيغة Gemini

​لماذا الصيغ المتعددة؟

​مقارنة الصيغ

​صيغة OpenAI

​صيغة Anthropic

​التفكير الموسّع (Claude Opus 4.6)

​صيغة Gemini

​البث

​حدود توافق الأدوات

​اختيار الصيغة المناسبة

​أدلة الترحيل

​من واجهة OpenAI الرسمية

​من واجهة Anthropic الرسمية

​من Google AI Studio

​توافق Chat المحمول

​حدود Responses وGemini

نظرة عامة

لماذا الصيغ المتعددة؟

مقارنة الصيغ

صيغة OpenAI

صيغة Anthropic

التفكير الموسّع (Claude Opus 4.6)

صيغة Gemini

البث

حدود توافق الأدوات

اختيار الصيغة المناسبة

أدلة الترحيل

من واجهة OpenAI الرسمية

من واجهة Anthropic الرسمية

من Google AI Studio

توافق Chat المحمول

حدود Responses وGemini