Chat Completions

نظرة عامة

تُعد نقطة النهاية Chat Completions أكثر واجهات API استخدامًا للتفاعل مع نماذج اللغة الكبيرة. فهي تقبل محادثة مكوّنة من عدة رسائل وتُرجع استجابة النموذج. تقوم CometAPI بتوجيه نقطة النهاية هذه إلى عدة مزودين — بما في ذلك OpenAI وAnthropic Claude (عبر طبقة توافق) وGoogle Gemini وغيرهم — من خلال واجهة موحدة واحدة. يمكنك التبديل بين النماذج بمجرد تغيير المعامل model.

تتبع نقطة النهاية هذه تنسيق OpenAI Chat Completions. تعمل معظم SDKs والأدوات المتوافقة مع OpenAI مع CometAPI بمجرد تغيير base_url إلى https://api.cometapi.com/v1.

ملاحظات مهمة

سلوك خاص بالنموذج — قد تدعم النماذج المختلفة مجموعات فرعية مختلفة من المعاملات وقد تُرجع حقول استجابة مختلفة قليلًا. على سبيل المثال، reasoning_effort ينطبق فقط على نماذج الاستدلال (o-series, GPT-5.1+)، وقد لا تدعم بعض النماذج logprobs أو n > 1.

تمرير الاستجابة كما هي — تقوم CometAPI بتمرير استجابات النموذج دون تعديل (باستثناء توحيد التنسيق عند التوجيه بين المزودين)، مما يضمن أنك تتلقى مخرجات متسقة مع الـ API الأصلي.

نماذج OpenAI Pro — بالنسبة إلى نماذج سلسلة OpenAI Pro (مثل o1-pro)، استخدم نقطة النهاية responses بدلًا من ذلك.

أدوار الرسائل

Role	Description
`system`	يحدد سلوك المساعد وشخصيته. يوضع في بداية المحادثة.
`developer`	يستبدل `system` في النماذج الأحدث (o1+). يوفّر تعليمات يجب على النموذج اتباعها بغض النظر عن مدخلات المستخدم.
`user`	رسائل من المستخدم النهائي.
`assistant`	استجابات النموذج السابقة، وتُستخدم للحفاظ على سجل المحادثة.
`tool`	نتائج استدعاءات الأدوات/الدوال. يجب أن تتضمن `tool_call_id` يطابق استدعاء الأداة الأصلي.

بالنسبة إلى النماذج الأحدث (GPT-4.1 وGPT-5 series وo-series)، يُفضّل استخدام developer بدلًا من system لرسائل التعليمات. كلاهما يعمل، لكن developer يوفّر سلوكًا أقوى في اتباع التعليمات.

الإدخال Multimodal

تدعم العديد من النماذج الصور والصوت إلى جانب النص. استخدم تنسيق المصفوفة في content لإرسال رسائل متعددة الوسائط:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe this image"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png",
        "detail": "high"
      }
    }
  ]
}

يتحكم المعامل detail في عمق تحليل الصورة:

low — أسرع، ويستخدم عددًا أقل من Tokens (تكلفة ثابتة)
high — تحليل مفصل، مع استهلاك عدد أكبر من Tokens
auto — يقرر النموذج ذلك (الافتراضي)

Streaming

عند تعيين stream إلى true، يتم تسليم الاستجابة على شكل Server-Sent Events (SSE). يحتوي كل حدث على كائن chat.completion.chunk مع محتوى تزايدي:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

لتضمين إحصاءات استخدام Token في استجابات Streaming، عيّن stream_options.include_usage إلى true. تظهر بيانات الاستخدام في الجزء الأخير قبل [DONE].

Structured Outputs

أجبر model على إرجاع JSON صالح يطابق schema محددًا باستخدام response_format:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        },
        "required": ["answer", "confidence"],
        "additionalProperties": false
      }
    }
  }
}

يضمن وضع JSON Schema (json_schema) أن يطابق الإخراج schema الخاص بك تمامًا. أما وضع JSON Object (json_object) فيضمن فقط JSON صالحًا — ولا يتم فرض البنية.

Tool / Function Calling

فعّل model لاستدعاء وظائف خارجية من خلال توفير تعريفات الأدوات:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

عندما يقرر model استدعاء أداة، ستكون الاستجابة تحتوي على finish_reason: "tool_calls" وستحتوي المصفوفة message.tool_calls على اسم الوظيفة والوسائط. بعد ذلك، تنفّذ الوظيفة وترسل النتيجة مرة أخرى كرسالة tool مع tool_call_id المطابق.

Response Fields

Field	Description
`id`	معرّف فريد للإكمال (مثلًا `chatcmpl-abc123`).
`object`	دائمًا `chat.completion`.
`model`	الـ model الذي أنشأ الاستجابة (قد يتضمن لاحقة إصدار).
`choices`	مصفوفة من خيارات الإكمال (عادةً 1 ما لم يكن `n` > 1).
`choices[].message`	رسالة استجابة المساعد وتتضمن `role` و`content` و`tool_calls` اختياريًا.
`choices[].finish_reason`	سبب توقف model: `stop` أو `length` أو `tool_calls` أو `content_filter`.
`usage`	تفصيل استهلاك Token: `prompt_tokens` و`completion_tokens` و`total_tokens` بالإضافة إلى الأعداد الفرعية التفصيلية.
`system_fingerprint`	بصمة إعدادات الواجهة الخلفية لأغراض تصحيح قابلية إعادة الإنتاج.

ملاحظات عبر المزوّدين

دعم المعلمات عبر المزوّدين

Parameter	OpenAI GPT	Claude (via compat)	Gemini (via compat)
`temperature`	0–2	0–1	0–2
`top_p`	0–1	0–1	0–1
`n`	1–128	1 فقط	1–8
`stop`	حتى 4	حتى 4	حتى 5
`tools`	✅	✅	✅
`response_format`	✅	✅ (json_schema)	✅
`logprobs`	✅	❌	❌
`reasoning_effort`	o-series، GPT-5.1+	❌	❌ (استخدم `thinking` لـ Gemini native)

max_tokens مقابل max_completion_tokens

max_tokens — المعلمة القديمة. تعمل مع معظم النماذج لكنها مهجورة في نماذج OpenAI الأحدث.
max_completion_tokens — المعلمة الموصى بها لسلسلة GPT-4.1 وGPT-5 ونماذج o-series. وهي مطلوبة لنماذج reasoning لأنها تشمل كلاً من output tokens وreasoning tokens.

يتولى CometAPI تلقائيًا معالجة الربط عند التوجيه إلى مزوّدين مختلفين.

دور system مقابل developer

system — دور التعليمات التقليدي. يعمل مع جميع النماذج.
developer — تم تقديمه مع نماذج o1. يوفّر اتباعًا أقوى للتعليمات في النماذج الأحدث. ويعود إلى سلوك system في النماذج الأقدم.

استخدم developer في المشاريع الجديدة التي تستهدف GPT-4.1+ أو نماذج o-series.

الأسئلة الشائعة

كيف أتعامل مع حدود المعدل؟

عند مواجهة 429 Too Many Requests، نفّذ exponential backoff:

import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key="<COMETAPI_KEY>",
)

def chat_with_retry(messages, max_retries=3):
    for i in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-5.4",
                messages=messages,
            )
        except RateLimitError:
            if i < max_retries - 1:
                wait_time = (2 ** i) + random.random()
                time.sleep(wait_time)
            else:
                raise

كيف أحافظ على سياق المحادثة؟

ضمّن سجل المحادثة الكامل داخل مصفوفة messages:

messages = [
    {"role": "developer", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a high-level programming language..."},
    {"role": "user", "content": "What are its main advantages?"},
]

ماذا يعني `finish_reason`؟

Value	Meaning
`stop`	اكتمال طبيعي أو الوصول إلى stop sequence.
`length`	تم الوصول إلى حد `max_tokens` أو `max_completion_tokens`.
`tool_calls`	استدعى النموذج استدعاء أداة/دالة واحدًا أو أكثر.
`content_filter`	تمت تصفية المخرجات بسبب سياسة المحتوى.

كيف أتحكم في التكاليف؟

استخدم max_completion_tokens لتحديد حد أقصى لطول المخرجات.
اختر نماذج فعّالة من حيث التكلفة (مثل gpt-5.4-mini أو gpt-5.4-nano للمهام الأبسط).
اجعل prompts موجزة — وتجنب السياق الزائد عن الحاجة.
راقب استخدام Token في حقل الاستجابة usage.

التفويضات

Authorization

string

header

مطلوب

Bearer token authentication. Use your CometAPI key.

الجسم

application/json

model

string

افتراضي:gpt-5.4

مطلوب

Model ID to use for this request. See the Models page for current options.

مثال:

"gpt-4.1"

messages

object[]

مطلوب

A list of messages forming the conversation. Each message has a role (system, user, assistant, or developer) and content (text string or multimodal content array).

Show child attributes

stream

boolean

If true, partial response tokens are delivered incrementally via server-sent events (SSE). The stream ends with a data: [DONE] message.

temperature

number

افتراضي:1

Sampling temperature between 0 and 2. Higher values (e.g., 0.8) produce more random output; lower values (e.g., 0.2) make output more focused and deterministic. Recommended to adjust this or top_p, but not both.

النطاق المطلوب: 0 <= x <= 2

top_p

number

افتراضي:1

Nucleus sampling parameter. The model considers only the tokens whose cumulative probability reaches top_p. For example, 0.1 means only the top 10% probability tokens are considered. Recommended to adjust this or temperature, but not both.

النطاق المطلوب: 0 <= x <= 1

integer

افتراضي:1

Number of completion choices to generate for each input message. Defaults to 1.

stop

string

Up to 4 sequences where the API will stop generating further tokens. Can be a string or an array of strings.

max_tokens

integer

Maximum number of tokens to generate in the completion. The total of input + output tokens is capped by the model's context length.

presence_penalty

number

افتراضي:0

Number between -2.0 and 2.0. Positive values penalize tokens based on whether they have already appeared, encouraging the model to explore new topics.

النطاق المطلوب: -2 <= x <= 2

frequency_penalty

number

افتراضي:0

Number between -2.0 and 2.0. Positive values penalize tokens proportionally to how often they have appeared, reducing verbatim repetition.

النطاق المطلوب: -2 <= x <= 2

logit_bias

object

A JSON object mapping token IDs to bias values from -100 to 100. The bias is added to the model's logits before sampling. Values between -1 and 1 subtly adjust likelihood; -100 or 100 effectively ban or force selection of a token.

user

string

A unique identifier for your end-user. Helps with abuse detection and monitoring.

max_completion_tokens

integer

An upper bound for the number of tokens to generate, including visible output tokens and reasoning tokens. Use this instead of max_tokens for GPT-4.1+, GPT-5 series, and o-series models.

response_format

object

Specifies the output format. Use {"type": "json_object"} for JSON mode, or {"type": "json_schema", "json_schema": {...}} for strict structured output.

Show child attributes

tools

object[]

A list of tools the model may call. Currently supports function type tools.

Show child attributes

tool_choice

افتراضي:auto

Controls how the model selects tools. auto (default): model decides. none: no tools. required: must call a tool.

logprobs

boolean

افتراضي:false

Whether to return log probabilities of the output tokens.

top_logprobs

integer

Number of most likely tokens to return at each position (0-20). Requires logprobs to be true.

النطاق المطلوب: 0 <= x <= 20

reasoning_effort

enum<string>

Controls the reasoning effort for o-series and GPT-5.1+ models.

الخيارات المتاحة:

low,

medium,

high

stream_options

object

Options for streaming. Only valid when stream is true.

Show child attributes

service_tier

enum<string>

Specifies the processing tier.

الخيارات المتاحة:

auto,

default,

flex,

priority

الاستجابة

200 - application/json

Successful chat completion response.

string

Unique completion identifier.

مثال:

"chatcmpl-abc123"

object

enum<string>

الخيارات المتاحة:

chat.completion

مثال:

"chat.completion"

created

integer

Unix timestamp of creation.

مثال:

1774412483

model

string

The model used (may include version suffix).

مثال:

"gpt-5.4-2025-07-16"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Show child attributes

service_tier

string

مثال:

"default"

system_fingerprint

string | null

مثال:

"fp_490a4ad033"

نظرة عامة

مرجع API

أدلة التكامل

الأخطاء

الأسعار والفوترة

الدعم

نظرة عامة

ملاحظات مهمة

أدوار الرسائل

الإدخال Multimodal

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

ملاحظات عبر المزوّدين

الأسئلة الشائعة

كيف أتعامل مع حدود المعدل؟

كيف أحافظ على سياق المحادثة؟

ماذا يعني `finish_reason`؟

كيف أتحكم في التكاليف؟

التفويضات

الجسم

الاستجابة

نظرة عامة

مرجع API

أدلة التكامل

الأخطاء

الأسعار والفوترة

الدعم

​نظرة عامة

​ملاحظات مهمة

​أدوار الرسائل

​الإدخال Multimodal

​Streaming

​Structured Outputs

​Tool / Function Calling

​Response Fields

​ملاحظات عبر المزوّدين

​الأسئلة الشائعة

​كيف أتعامل مع حدود المعدل؟

​كيف أحافظ على سياق المحادثة؟

​ماذا يعني finish_reason؟

​كيف أتحكم في التكاليف؟

التفويضات

الجسم

الاستجابة

نظرة عامة

ملاحظات مهمة

أدوار الرسائل

الإدخال Multimodal

Streaming

Structured Outputs

Tool / Function Calling

Response Fields

ملاحظات عبر المزوّدين

الأسئلة الشائعة

كيف أتعامل مع حدود المعدل؟

كيف أحافظ على سياق المحادثة؟

ماذا يعني `finish_reason`؟

كيف أتحكم في التكاليف؟