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

تنسيقات 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 بتمرير الحقول التي لا يتعرف عليها، ولكن هذا لا يعني أن كل نموذج يقبلها. من الآمن الاعتماد على ميزة ما فقط عندما يوثقها النموذج المحدد ويقوم تطبيقك بمعالجة خطأ الحقل غير المدعوم.

مراجع ذات صلة

في هذه الصفحة