الأدلة الأساسية
تنسيقات API
اختر بين Chat Completions أو Responses أو Messages أو Gemini
يعمل مفتاح API الخاص بـ TokenLab مع أربعة تنسيقات شائعة لـ API. احتفظ بالتنسيق الذي يستخدمه تطبيقك بالفعل ما لم تكن بحاجة إلى ميزة خاصة بنموذج معين.
| التنسيق | نقطة النهاية (Endpoint) | اختره عندما |
|---|---|---|
| Chat Completions | /v1/chat/completions | تستخدم عميل دردشة متوافق مع OpenAI أو ترغب في توافق واسع مع النماذج |
| Responses | /v1/responses | يستخدم تطبيقك أحداث Responses، أو الاستجابات في الخلفية، أو أدوات Responses |
| Anthropic Messages | /v1/messages | تحتاج إلى حقول Claude Messages مثل التفكير (thinking) أو استخدام أدوات Claude |
| Gemini | /v1beta/models/:model:generateContent | تستخدم بالفعل contents الخاصة بـ Gemini، أو الأجزاء (parts)، أو الملفات، أو التخزين المؤقت، أو أدوات Gemini |
تحقق من tokenlab.accepted_request_formats في صفحة النموذج أو في GET /v1/models/{model}. لا يقبل النموذج بالضرورة جميع التنسيقات الأربعة.
Chat Completions
يعد Chat Completions الخيار الأسهل لعملاء OpenAI الحاليين المتوافقين وميزات الدردشة القابلة للنقل.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.chat.completions.create(
model="gpt-5.6-luna",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)استخدم هذا التنسيق من أجل:
- عمليات تكامل الدردشة الحالية المتوافقة مع OpenAI
- سجل الرسائل القياسي والبث (streaming)
- استدعاء الدوال (function calling) المدعوم من قبل النموذج المحدد
الحقول الفريدة لتنسيق API آخر غير مضمونة للعمل هنا.
Responses
استخدم Responses فقط عندما يسرد النموذج المحدد openai_responses ضمن accepted_request_formats.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.responses.create(
model="gpt-5.6-terra",
input="Explain why the sky is blue in two sentences.",
)
print(response.output_text)يدعم Responses API الإنشاء، والاسترجاع، والضغط، والحذف، والبث، وإنشاء واستمرار WebSocket، والاستجابات في الخلفية حيثما يدعمها النموذج المحدد. يقوم الحذف بإزالة استجابة مخزنة؛ ولا يؤدي إلى إلغاء استجابة نشطة.
Anthropic Messages
استخدم Anthropic SDK مع مضيف TokenLab، دون إضافة /v1 إلى عنوان URL الأساسي.
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)اختر Messages لحقول الطلب والاستجابة الخاصة بـ Claude. احتفظ باستدعاءات أدوات Claude، وكتل التفكير، وحقول التخزين المؤقت للمطالبات (prompt-cache) في هذا التنسيق.
Gemini
تستخدم طلبات Gemini مضيف TokenLab ومسار REST الخاص بـ Gemini.
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.6-flash:generateContent" \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Hello!"}]}]
}'اختر Gemini عندما يستخدم تطبيقك بالفعل أجزاء محتوى Gemini، أو تعريفات الدوال، أو الملفات، أو المحتوى المخزن مؤقتاً، أو حقول Gemini الأخرى. يتم قبول كل من أسماء ProtoJSON بتنسيق lowerCamelCase وأسماء proto الأصلية بتنسيق snake_case؛ تجنب إرسال كلتا الصيغتين لنفس الحقل في طلب واحد.
لا تخلط بين التنسيقات في محادثة واحدة
تمثل Messages و Responses و Chat Completions و Gemini حالة المحادثة واستدعاءات الأدوات بشكل مختلف. التزم بتنسيق واحد لكل محادثة. إذا كان يجب عليك ترحيل السجل المخزن، فقم بتحويله والتحقق من صحته في تطبيقك قبل إرسال الطلب التالي.
الحقول غير المعروفة
قد يقوم TokenLab بتمرير الحقول التي لا يتعرف عليها، ولكن هذا لا يعني أن كل نموذج يقبلها. من الآمن الاعتماد على ميزة ما فقط عندما يوثقها النموذج المحدد ويقوم تطبيقك بمعالجة خطأ الحقل غير المدعوم.