TokenLab
الحصول على مفتاح API
التوثيقمرجع APIالتكاملات

النص

إنشاء إكمال المحادثة (Chat Completion)

إنشاء إكمال لرسالة المحادثة

POST
/v1/chat/completions

نص الطلب (Request Body)

تعتمد المعلمات الاختيارية المدعومة، والقيم المقبولة، والقيم الافتراضية على النموذج المختار. تحقق من تفاصيل النموذج قبل ضبط خيارات أخذ العينات (sampling)، أو التفكير (reasoning)، أو الأدوات.

modelstringمطلوب

معرف النموذج المراد استخدامه. راجع النماذج للاطلاع على الخيارات المتاحة.

messagesarrayمطلوب

قائمة بالرسائل التي تتكون منها المحادثة.

يحتوي كل كائن رسالة على:

  • role (string): system، developer، user، assistant، tool، function
  • content (string | array | null): محتوى الرسالة

بالنسبة لرسالة assistant التي تحتوي على tool_calls، يمكن حذف content أو ضبطه على null.

عندما يكون content عبارة عن مصفوفة، يدعم TokenLab كتل الوسائط المتعددة المهيكلة للنماذج المتوافقة:

  • نص: { "type": "text", "text": "..." }
  • صورة: { "type": "image_url", "image_url": { "url": "https://..." } }
  • فيديو: { "type": "video_url", "video_url": { "url": "https://..." } }
  • صوت: { "type": "audio_url", "audio_url": { "url": "https://..." } }

بالنسبة لمدخلات الوسائط المتعددة، استخدم روابط https يمكن الوصول إليها علنًا. تعتمد أنواع الوسائط المدعومة على النموذج المختار.

temperaturenumber

درجة حرارة أخذ العينات (Sampling temperature). يعتمد الدعم والقيم المسموح بها والقيمة الافتراضية على النموذج المختار؛ احذف هذا الحقل لاستخدام القيمة الافتراضية.

max_tokensinteger

الحد الأقصى لعدد الرموز (tokens) المراد إنشاؤها.

بالنسبة إلى deepseek-v4.1-flash (والاسم المستعار deepseek-flash)، يبدأ النموذج بالتفكير افتراضيًا. تُحتسب رموز التفكير ضمن max_tokens. إذا كانت قيمة max_tokens صغيرة جدًا، فقد تُستهلك الميزانية كلها في التفكير ويبقى نص الرسالة فارغًا مع احتساب تكلفة الطلب. للإجابات الطويلة، يُفضَّل ضبط max_tokens على نحو 32000، أو إيقاف التفكير. لإيقاف التفكير، أضف "thinking": {"type": "disabled"} (أو "reasoning_effort": "none") إلى جسم الطلب؛ ويعمل ذلك مع الطلبات المتدفقة وغير المتدفقة. أما "enable_thinking": false و"reasoning": {"enabled": false} فلا يوقفان التفكير.

streambooleanالافتراضي: false

إذا تم ضبطه على true، فسيتم إرسال دلتا الرسائل الجزئية كأحداث SSE.

للمخرجات الطويلة (آلاف الرموز أو أكثر)، اضبط stream=true حتى لا تنتهي مهلة العملاء غير المتدفقين أثناء انتظار الاستجابة الكاملة. قياس الفريق: استغرق GPT-6.1 Sol نحو 147 ثانية لإنتاج قرابة 12 ألف حرف دون تدفق.

stream_optionsobject

خيارات البث (streaming). اضبط include_usage: true لتلقي استخدام الرموز في أجزاء البث.

top_pnumber

معلمة أخذ عينات النواة (Nucleus sampling). نوصي بتغيير هذه المعلمة أو درجة الحرارة، وليس كليهما.

frequency_penaltynumber

رقم بين -2.0 و 2.0. القيم الموجبة تعاقب الرموز المتكررة.

presence_penaltynumber

رقم بين -2.0 و 2.0. القيم الموجبة تعاقب الرموز الموجودة بالفعل في النص.

stopstring | array

تسلسل التوقف أو قائمة بالتسلسلات. يعتمد الدعم وحدود التسلسل على النموذج المختار.

toolsarray

قائمة بالأدوات التي قد يستدعيها النموذج (استدعاء الوظائف).

tool_choicestring | object

يتحكم في كيفية استخدام النموذج للأدوات. الخيارات: auto، none، required، أو كائن أداة محدد.

parallel_tool_callsboolean

السماح باستدعاءات أدوات متعددة في دور مساعد واحد، عند دعم ذلك من قبل النموذج المختار.

max_completion_tokensinteger

الحد الأقصى للرموز للإكمال. بديل لـ max_tokens، مفيد لعائلات النماذج الأحدث التي تدعم التفكير.

reasoning_effortstring

جهد التفكير للنماذج التي تدعمه. تعتمد القيم المقبولة على النموذج المختار.

بالنسبة لنماذج Claude، تحدد القيمة تفكير النموذج: مستوى جهد في النماذج ذات التفكير التكيفي، أو ميزانية تفكير في النماذج التي تستخدم واحدة. none تعطل التفكير في النماذج التي تسمح بذلك. أثناء تشغيل التفكير، يرفض Claude أي temperature غير 1، و top_k، و top_p خارج نطاق 0.95–1، ورسالة مساعد مملوءة مسبقًا. يعمل tool_choice القسري مع التفكير التكيفي ولكن ليس مع ميزانية التفكير.

anthropic_optionsobject

خيارات لنماذج Claude.

  • prompt_caching (boolean): اضبط على true لتخزين بداية المطالبة (prompt) مؤقتًا. يحدد TokenLab نهاية مطالبة النظام وأحدث رسالة مستخدم كنقاط تخزين مؤقت. الطلب اللاحق الذي يبدأ بنفس المحتوى يقرأه من ذاكرة التخزين المؤقت. إذا كانت أي رسالة تحتوي بالفعل على cache_control، فلن يضيف TokenLab أي نقاط تخزين مؤقت.
  • prompt_caching_ttl (string): 5m (افتراضي) أو 1h. إذا كان مسار الخدمة لا يدعم ساعة واحدة، يستخدم TokenLab خمس دقائق ولا يرفض الطلب.

يتم قبول extra.prompt_caching و extra.prompt_caching_ttl كخيارات مماثلة. راجع تخزين المطالبة مؤقتًا لمعرفة الأسعار وكيفية التحقق من الرموز المخزنة مؤقتًا.

seedinteger

بذرة أخذ العينات (Sampling seed) للنماذج التي تدعمها. لا يوجد ضمان للحصول على مخرجات متطابقة.

ninteger

عدد عمليات الإكمال المراد إنشاؤها (1-128).

logprobsboolean

ما إذا كان سيتم إرجاع احتمالات السجل (log probabilities).

top_logprobsinteger

عدد احتمالات السجل العليا المراد إرجاعها (0-20). يتطلب logprobs: true.

top_kinteger

أخذ عينات Top-K للنماذج التي تدعمها.

response_formatobject

تنسيق الاستجابة. استخدم {"type": "json_object"} لوضع JSON أو {"type": "json_schema", "json_schema": {...}} لمخطط JSON. يعتمد الدعم على النموذج المختار.

logit_biasobject

تعديل احتمالية ظهور رموز محددة. قم بتعيين معرفات الرموز (كسلاسل نصية) إلى قيم انحياز من -100 إلى 100.

userstring

معرف فريد يمثل المستخدم النهائي الخاص بك لمراقبة الإساءة.

الاستجابة (Response)

idstring

معرف فريد لعملية الإكمال.

objectstring

دائمًا chat.completion.

createdinteger

طابع زمني بنظام Unix لوقت إنشاء الإكمال.

modelstring

النموذج المستخدم للإكمال.

choicesarray

قائمة بخيارات الإكمال.

يحتوي كل خيار على:

  • index (integer): فهرس الخيار
  • message (object): الرسالة التي تم إنشاؤها
  • finish_reason (string): سبب توقف النموذج، على سبيل المثال stop، أو length، أو tool_calls

عندما يفكر النموذج، يمكن أن تحتوي message أيضًا على:

  • reasoning_content (string): نص التفكير. بعض النماذج تعيد ملخصًا فقط، أو لا تعيد أي نص.
  • reasoning_details (array): كتل التفكير مع توقيعاتها. لمواصلة محادثة مع التفكير، على سبيل المثال بعد استدعاء أداة، أرسلها مرة أخرى دون تغيير في رسالة المساعد.

في البث، تصل نفس الحقول كـ delta.reasoning_content و delta.reasoning_details.

usageobject

إحصائيات استخدام الرموز.

  • prompt_tokens (integer): الرموز في المطالبة
  • completion_tokens (integer): الرموز في الإكمال، بما في ذلك رموز التفكير
  • total_tokens (integer): إجمالي الرموز المستخدمة
  • completion_tokens_details.reasoning_tokens (integer): رموز التفكير، عندما يبلغ عنها النموذج

الطلب

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

مثال على الوسائط المتعددة (Multimodal Example)

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

الاستجابة

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

الحصول على الأسعار

السابق

إنشاء استجابة

التالي