النص

إنشاء إكمال الدردشة

ينشئ إكمالاً لرسالة الدردشة

POST
/v1/chat/completions

جسم الطلب

تعتمد المعلمات الاختيارية المدعومة والقيم المقبولة والقيم الافتراضية على النموذج المحدد. تحقق من تفاصيل النموذج قبل تعيين خيارات أخذ العينات (sampling) أو التفكير المنطقي (reasoning) أو الأدوات. يتم رفض أي عنصر تحكم لا يمكن للنموذج الالتزام به، مثل تعيين n بقيمة أكبر من 1 في بعض النماذج، مع ظهور خطأ من فئة 4xx. بينما يمكن تجاهل عناصر التحكم الثانوية لأخذ العينات، مثل seed أو معلمات العقوبة (penalties)، بدلاً من ذلك.

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": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } }، أو { "type": "audio_url", "audio_url": { "url": "https://..." } }

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

temperaturenumber

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

max_tokensinteger

الحد الأقصى لعدد الـ tokens المراد إنشاؤها. أرسل إما max_tokens أو max_completion_tokens، وليس كليهما: فالنموذج الذي يتم تقديمه عبر بروتوكول آخر قد يرفض الطلب الذي يتضمن كليهما.

في النماذج التي تدعم التفكير، تُحتسب tokens التفكير ضمن هذا الحد. وإذا كان الحد صغيراً جداً، فقد تُستهلك الميزانية بالكامل في التفكير وتترك نص الرسالة فارغاً، مع استمرار فوترة الـ tokens المستخدمة. ارفع الحد، أو أوقف تشغيل التفكير حيثما يسمح النموذج بذلك، على سبيل المثال باستخدام "reasoning_effort": "none". وفي deepseek-v4.1-flash (الاسم المستعار deepseek-flash)، يؤدي الإعداد "thinking": {"type": "disabled"} أيضاً إلى إيقاف تشغيله.

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

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

إذا كانت القيمة true، يتم إرسال أجزاء الرسالة الجزئية كأحداث مرسلة من الخادم (SSE). راجع البث المباشر.

بالنسبة للمخرجات الطويلة (آلاف الـ tokens أو أكثر)، اضبط stream: true حتى لا تنتهي مهلة انتظار العملاء والوكلاء (proxies) أثناء انتظار الاستجابة الكاملة.

stream_optionsobject

خيارات البث. اضبط include_usage: true لتلقي كتلة إضافية واحدة تتضمن استهلاك الـ tokens قبل data: [DONE]. بدونها، لا يتضمن البث بيانات الاستهلاك.

top_pnumber

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

frequency_penaltynumber

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

presence_penaltynumber

رقم بين -2.0 و 2.0. تعاقب القيم الموجبة الـ tokens الموجودة مسبقاً في النص.

stopstring | array

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

toolsarray

قائمة بالأدوات التي قد يستدعيها النموذج (استدعاء الدوال - function calling). كل أداة تكون على شكل { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. راجع المخرجات المهيكلة واستدعاء الأدوات.

tool_choicestring | object

يتحكم في كيفية استخدام النموذج للأدوات. الخيارات: auto أو none أو required، أو { "type": "function", "function": { "name": "..." } } لفرض استخدام أداة معينة.

parallel_tool_callsboolean

السماح باستدعاءات متعددة للأدوات في جولة واحدة للـ assistant، عندما يكون ذلك مدعوماً من النموذج المحدد.

max_completion_tokensinteger

الحد الأقصى للإكمال، بما في ذلك tokens التفكير. وهو بديل لـ max_tokens مستخدم في عائلات نماذج OpenAI الأحدث. أرسل واحداً فقط من الاثنين.

reasoning_effortstring

مستوى جهد التفكير (Reasoning effort) للنماذج التي تدعمه. تعتمد القيم المقبولة على النموذج المحدد.

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

anthropic_optionsobject

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

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

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

seedinteger

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

ninteger

عدد الإكمالات المراد إنشاؤها. تقبل النماذج التي تدعم ذلك قيماً بين 1 و128. والعديد من النماذج تدعم 1 فقط.

logprobsboolean

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

top_logprobsinteger

عدد أعلى الاحتمالات اللوغاريتمية المراد إرجاعها (0-20). يتطلب logprobs: true.

top_kinteger

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

response_formatobject

تنسيق الاستجابة. استخدم {"type": "text"} (افتراضي)، أو {"type": "json_object"} لوضع JSON، أو {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} لمخطط JSON schema. يعتمد الدعم على النموذج المحدد. راجع المخرجات المهيكلة واستدعاء الأدوات.

logit_biasobject

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

service_tierstring

يقدم TokenLab طلبات Chat ويفوترها وفقاً لمستوى الخدمة القياسي. يتم قبول auto و default. أما القيم الأخرى، مثل flex أو priority، فيتم إزالتها من الطلب، وتتم فوترة الطلب بالسعر القياسي.

userstring

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

الاستجابة

idstring

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

objectstring

دائماً chat.completion.

createdinteger

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

modelstring

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

choicesarray

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

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

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

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

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

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

usageobject

إحصائيات استخدام الـ tokens.

  • prompt_tokens (integer): الـ tokens الموجودة في الـ prompt
  • completion_tokens (integer): الـ tokens الموجودة في الإكمال، بما في ذلك tokens التفكير
  • total_tokens (integer): إجمالي الـ tokens المستخدمة
  • prompt_tokens_details.cached_tokens (integer): الـ tokens الخاصة بالـ prompt المقروءة من الذاكرة المؤقتة (cache)
  • cache_creation_input_tokens (integer): الـ tokens الخاصة بالـ prompt المكتوبة في الذاكرة المؤقتة (cache). تظهر فقط عندما تكون القيمة أكبر من 0
  • completion_tokens_details.reasoning_tokens (integer): tokens التفكير، عندما يقدم النموذج تقريراً عنها

في البث المباشر، لا تصل بيانات الاستخدام إلا عندما تكون قيمة stream_options.include_usage هي true.

الطلب

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
  }'

مثال على الوسائط المتعددة

{
  "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
  }
}

البث المباشر

عند تعيين stream: true، تكون الاستجابة من نوع text/event-stream. كل حدث يكون على شكل data: {...} يحتوي على كائن chat.completion.chunk حيث يحمل choices[].delta النص الجديد، أو وسائط استدعاء الأداة، أو نص التفكير. ينتهي البث بـ data: [DONE]. السطور التي تبدأ بـ : هي تعليقات لإبقاء الاتصال نشطاً (keep-alive): يمكنك تجاهلها. يعتبر البث الذي ينتهي دون [DONE] أو دون finish_reason غير مكتمل. راجع البث المباشر.

الأخطاء

تستخدم الأخطاء كائن error بأسلوب OpenAI. الحالات الشائعة: 400 لحقل غير صالح أو قيمة لا يقبلها النموذج، و401 لمفتاح غير صالح، و402 لعدم كفاية الرصيد، و413 للمدخلات التي تتجاوز حد الحجم، و429 لتجاوز حد المعدل (rate limit). راجع التعامل مع أخطاء API.

التفويض

BearerAuth
AuthorizationBearer <token>

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

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

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

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

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يمنع تشغيل الطلب نفسه مرة ثانية. أرسل قيمة فريدة جديدة، مثل UUID، لكل طلب، واحتفظ بها لعمليات إعادة المحاولة بعد انتهاء المهلة. إعادة المحاولة باستخدام نفس المفتاح لا تؤدي إلى تشغيل الطلب مجدداً: بل تُرجع 409 مع idempotency_replay_unavailable، أو عادةً idempotency_conflict عند تغيير نص الطلب. استثناء: عندما تكتمل نتيجة غير streaming بعد قطع اتصال العميل، فإن إعادة المحاولة بنفس المفتاح ونص الطلب خلال 24 ساعة تُرجع تلك النتيجة (بحد أقصى 1 ميجابايت) مع الترويسة Idempotent-Replayed: true دون احتساب تكلفة إضافية. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json