النص
إنشاء إكمال الدردشة
ينشئ إكمالاً لرسالة الدردشة
جسم الطلب
تعتمد المعلمات الاختيارية المدعومة والقيم المقبولة والقيم الافتراضية على النموذج المحدد. تحقق من تفاصيل النموذج قبل تعيين خيارات أخذ العينات (sampling) أو التفكير المنطقي (reasoning) أو الأدوات. يتم رفض أي عنصر تحكم لا يمكن للنموذج الالتزام به، مثل تعيين n بقيمة أكبر من 1 في بعض النماذج، مع ظهور خطأ من فئة 4xx. بينما يمكن تجاهل عناصر التحكم الثانوية لأخذ العينات، مثل seed أو معلمات العقوبة (penalties)، بدلاً من ذلك.
معرّف النموذج المراد استخدامه. راجع النماذج للاطلاع على الخيارات المتاحة.
قائمة بالرسائل التي تتألف منها المحادثة.
يحتوي كل كائن رسالة على:
role(string):system،developer،user،assistant،tool،functioncontent(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. وتعتمد أنواع الوسائط المدعومة على النموذج المحدد.
درجة حرارة أخذ العينات (Sampling temperature). يعتمد الدعم والقيم المسموح بها والقيمة الافتراضية على النموذج المحدد؛ اترك هذا الحقل فارغاً لاستخدام قيمته الافتراضية.
الحد الأقصى لعدد الـ tokens المراد إنشاؤها. أرسل إما max_tokens أو max_completion_tokens، وليس كليهما: فالنموذج الذي يتم تقديمه عبر بروتوكول آخر قد يرفض الطلب الذي يتضمن كليهما.
في النماذج التي تدعم التفكير، تُحتسب tokens التفكير ضمن هذا الحد. وإذا كان الحد صغيراً جداً، فقد تُستهلك الميزانية بالكامل في التفكير وتترك نص الرسالة فارغاً، مع استمرار فوترة الـ tokens المستخدمة. ارفع الحد، أو أوقف تشغيل التفكير حيثما يسمح النموذج بذلك، على سبيل المثال باستخدام "reasoning_effort": "none". وفي deepseek-v4.1-flash (الاسم المستعار deepseek-flash)، يؤدي الإعداد "thinking": {"type": "disabled"} أيضاً إلى إيقاف تشغيله.
قبل تنفيذ الطلب، يتحقق TokenLab من أن رصيدك يغطي هذا الحد الأقصى. قد تؤدي القيمة الكبيرة جداً إلى إرجاع خطأ 402 في حال كان الرصيد منخفضاً حتى لو كانت الإجابة قصيرة.
falseإذا كانت القيمة true، يتم إرسال أجزاء الرسالة الجزئية كأحداث مرسلة من الخادم (SSE). راجع البث المباشر.
بالنسبة للمخرجات الطويلة (آلاف الـ tokens أو أكثر)، اضبط stream: true حتى لا تنتهي مهلة انتظار العملاء والوكلاء (proxies) أثناء انتظار الاستجابة الكاملة.
خيارات البث. اضبط include_usage: true لتلقي كتلة إضافية واحدة تتضمن استهلاك الـ tokens قبل data: [DONE]. بدونها، لا يتضمن البث بيانات الاستهلاك.
معلمة أخذ العينات بالاحتمال التراكمي (Nucleus sampling). نوصي بتعديل هذه المعلمة أو temperature، وليس كليهما.
رقم بين -2.0 و 2.0. تعاقب القيم الموجبة الـ tokens المتكررة.
رقم بين -2.0 و 2.0. تعاقب القيم الموجبة الـ tokens الموجودة مسبقاً في النص.
تسلسل إيقاف أو قائمة من التسلسلات. يعتمد الدعم والحد الأقصى للتسلسلات على النموذج المحدد.
قائمة بالأدوات التي قد يستدعيها النموذج (استدعاء الدوال - function calling). كل أداة تكون على شكل { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. راجع المخرجات المهيكلة واستدعاء الأدوات.
يتحكم في كيفية استخدام النموذج للأدوات. الخيارات: auto أو none أو required، أو { "type": "function", "function": { "name": "..." } } لفرض استخدام أداة معينة.
السماح باستدعاءات متعددة للأدوات في جولة واحدة للـ assistant، عندما يكون ذلك مدعوماً من النموذج المحدد.
الحد الأقصى للإكمال، بما في ذلك tokens التفكير. وهو بديل لـ max_tokens مستخدم في عائلات نماذج OpenAI الأحدث. أرسل واحداً فقط من الاثنين.
مستوى جهد التفكير (Reasoning effort) للنماذج التي تدعمه. تعتمد القيم المقبولة على النموذج المحدد.
بالنسبة لنماذج Claude، تحدد القيمة نمط تفكير النموذج: مستوى الجهد في النماذج ذات التفكير التكيفي، أو ميزانية التفكير في النماذج التي تستخدمها. الخيار none يعطل التفكير في النماذج التي تسمح بذلك. أي قيمة لا يدعمها النموذج يتم رفضها بخطأ 400 مع الرمز invalid_value، وتوضح رسالة الخطأ القيم المدعومة. أثناء تفعيل التفكير، يرفض Claude تعيين temperature بقيمة غير 1، وtop_k، وtop_p خارج النطاق 0.95–1، ورسالة assistant المعبأة مسبقاً. ويعمل فرض tool_choice مع التفكير التكيفي ولكن ليس مع ميزانية التفكير.
خيارات لنماذج 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 المخزنة مؤقتاً.
قيمة البذرة (Sampling seed) لأخذ العينات في النماذج التي تدعمها. ولا يُضمن الحصول على مخرجات متطابقة.
عدد الإكمالات المراد إنشاؤها. تقبل النماذج التي تدعم ذلك قيماً بين 1 و128. والعديد من النماذج تدعم 1 فقط.
ما إذا كان سيتم إرجاع الاحتمالات اللوغاريتمية (log probabilities).
عدد أعلى الاحتمالات اللوغاريتمية المراد إرجاعها (0-20). يتطلب logprobs: true.
أخذ العينات Top-K للنماذج التي تدعمه.
تنسيق الاستجابة. استخدم {"type": "text"} (افتراضي)، أو {"type": "json_object"} لوضع JSON، أو {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} لمخطط JSON schema. يعتمد الدعم على النموذج المحدد. راجع المخرجات المهيكلة واستدعاء الأدوات.
تعديل احتمالية ظهور tokens محددة. قم بربط معرّفات الـ tokens (كسلاسل نصية) بقيم انحياز تتراوح من -100 إلى 100. يعتمد الدعم على النموذج المحدد.
يقدم TokenLab طلبات Chat ويفوترها وفقاً لمستوى الخدمة القياسي. يتم قبول auto و default. أما القيم الأخرى، مثل flex أو priority، فيتم إزالتها من الطلب، وتتم فوترة الطلب بالسعر القياسي.
معرّف فريد يمثل المستخدم النهائي الخاص بك لمراقبة إساءة الاستخدام.
الاستجابة
معرّف فريد للإكمال.
دائماً chat.completion.
طابع زمني بتنسيق Unix لوقت إنشاء الإكمال.
النموذج المستخدم للإكمال.
قائمة بخيارات الإكمال.
يحتوي كل خيار على:
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.
إحصائيات استخدام الـ tokens.
prompt_tokens(integer): الـ tokens الموجودة في الـ promptcompletion_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). تظهر فقط عندما تكون القيمة أكبر من 0completion_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
}الاستجابة
{
"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 مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يمنع تشغيل الطلب نفسه مرة ثانية. أرسل قيمة فريدة جديدة، مثل 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