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

POST

chat

completions

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)

{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

يوجّه CometAPI طلبات Chat Completions إلى عدة مزودين، بما في ذلك OpenAI وClaude وGemini، عبر واجهة واحدة متوافقة مع OpenAI. بدّل بين النماذج بتغيير المعلمة model؛ وتعمل معظم SDKs المتوافقة مع OpenAI عبر ضبط base_url على https://api.cometapi.com/v1.

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

بالنسبة إلى نماذج OpenAI Pro، ونماذج الاستدلال o-series، ونماذج Codex، استخدم نقطة النهاية Responses بدلاً من ذلك. تحظى عائلات النماذج هذه بدعم أكمل على Responses API.

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

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

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

إرسال إدخال Multimodal

تدعم العديد من النماذج الصور والصوت إلى جانب النص. لإرسال رسائل 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 — يقرر النموذج (الافتراضي)

بث الاستجابات

لتلقي ناتج تدريجي، اضبط 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]

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

طلب ناتج منظّم

لإجبار النموذج على إرجاع JSON صالح يطابق مخططًا محددًا، استخدم 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
      }
    }
  }
}

{
  "response_format": {"type": "json_object"}
}

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

استدعاء الأدوات والدوال

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

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

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

ملاحظات حول المزودين المختلفين

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

المعلمة	OpenAI GPT	Claude (عبر التوافق)	Gemini (عبر التوافق)
`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 الأصلي)

max_tokens مقابل max_completion_tokens

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

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

دور system مقابل developer

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

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

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

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

عند مواجهة 429 Too Many Requests، نفّذ تراجعًا أسيًا:

import os
import time
import random
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["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.6-sol",
                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`؟

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

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

استخدم max_completion_tokens للحد من طول الناتج.
استخدم gpt-5.6-terra لتحقيق توازن بين الذكاء والتكلفة، أو gpt-5.6-luna لأحمال العمل الفعالة وعالية الحجم.
حافظ على Prompt موجزًا — وتجنب السياق المكرر.
راقب استخدام Tokens في حقل الاستجابة usage.

التفويضات

Authorization

string

header

مطلوب

Bearer token authentication. Use your CometAPI key.

الجسم

application/json

model

string

افتراضي:gpt-5.6-sol

مطلوب

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

الاستجابة

Successful chat completion response.

string

Unique completion identifier.

مثال:

"chatcmpl-abc123"

object

enum<string>

Object type. Non-streaming responses use chat.completion.

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

chat.completion

مثال:

"chat.completion"

created

integer

Unix timestamp of creation.

مثال:

1774412483

model

string

The model used (may include version suffix).

مثال:

"gpt-5.4-2026-03-05"

choices

object[]

Array of completion choices.

Show child attributes

usage

object

Token accounting for this request. Billing uses these counts.

Show child attributes

service_tier

string

Service tier that processed the request, when the provider reports one.

مثال:

"default"

system_fingerprint

string | null

Provider backend configuration fingerprint, when the provider reports one.

مثال:

"fp_490a4ad033"

واجهات API للنصوص والدردشة

إنشاء استجابة نموذج

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.cometapi.com/v1",
    api_key=os.environ["COMETAPI_KEY"],
)

completion = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.choices[0].message)

{
  "id": "chatcmpl-DNA27oKtBUL8TmbGpBM3B3zhWgYfZ",
  "object": "chat.completion",
  "created": 1774412483,
  "model": "gpt-4.1-nano-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Four",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 2,
    "total_tokens": 31,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_490a4ad033"
}

{
  "error": {
    "code": "",
    "message": "model name is required (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "code": "",
    "message": "invalid token (request id: <request_id>)",
    "type": "comet_api_error"
  }
}

{
  "error": {
    "message": "field messages is required (request id: <request_id>)",
    "type": "comet_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

الإشراف على المحتوى

مفاتيح API

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

إرسال إدخال Multimodal

بث الاستجابات

طلب ناتج منظّم

استدعاء الأدوات والدوال

ملاحظات حول المزودين المختلفين

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

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

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

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

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

التفويضات

الجسم

الاستجابة

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

​إرسال إدخال Multimodal

​بث الاستجابات

​طلب ناتج منظّم

​استدعاء الأدوات والدوال

​ملاحظات حول المزودين المختلفين

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

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

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

​ماذا يعني finish_reason؟

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

التفويضات

الجسم

الاستجابة

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

إرسال إدخال Multimodal

بث الاستجابات

طلب ناتج منظّم

استدعاء الأدوات والدوال

ملاحظات حول المزودين المختلفين

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

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

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

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

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