صيغة OpenAI للمحادثة (Chat Completions)

الوثائق الرسمية

OpenAI Chat

📝 مقدّمة

عند إرسال قائمة من الرسائل تشكّل محادثة، يعيد النموذج ردًّا عليها. هذه هي الصيغة الأوسع توافقًا — إذ يمكن من خلالها استدعاء GPT وClaude وGemini وDeepSeek وGLM وKimi وQwen وGrok وجميع نماذج المحادثة الأخرى على البوابة.

📮 نقطة الوصول

POST /v1/chat/completions

المصادقة

أدرج مفتاح API في ترويسات الطلب:

Authorization: Bearer $WS_API_KEY

💡 أمثلة الطلبات

محادثة نصية أساسية ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

مثال على الاستجابة:

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29
  }
}

الاستجابة المتدفقة (Streaming) ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

مثال على الاستجابة المتدفقة (أحداث SSE):

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

تحليل الصور (الرؤية) ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {
            "type": "image_url",
            "image_url": {"url": "https://example.com/photo.jpg"}
          }
        ]
      }
    ],
    "max_tokens": 300
  }'

يقبل الحقل image_url.url رابطًا عامًا أو بيانات base64 ‏(data:image/jpeg;base64,...).

استدعاء الدوال (Function Calling) ✅

curl http://baseurl/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WS_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "What is the weather like in Dubai today?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather for a specified location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name, e.g. Dubai"},
              "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

مثال على الاستجابة:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\"location\": \"Dubai\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

استخدام حِزم SDK الرسمية

تعمل أي حزمة SDK متوافقة مع OpenAI — يكفي توجيه base_url إلى البوابة:

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",                     # مفتاح WS API الخاص بك
    base_url="http://baseurl/v1",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

📋 معاملات جسم الطلب

المعامل	النوع	مطلوب	الوصف
model	string	نعم	معرّف النموذج، راجع دليل النماذج
messages	array	نعم	رسائل المحادثة. الأدوار: system / developer وuser وassistant وtool
stream	boolean	لا	القيمة true تبثّ الاستجابة عبر أحداث SSE. الافتراضي false
stream_options	object	لا	‏{"include_usage": true} يضيف قطعة أخيرة تتضمن إحصاءات الرموز عند التدفق
temperature	number	لا	حرارة أخذ العينات 0–2. الافتراضي 1. الأعلى = عشوائية أكبر
top_p	number	لا	أخذ عينات نووي. بديل عن temperature؛ لا تغيّر كليهما معًا
max_completion_tokens	integer	لا	الحد الأقصى للرموز المولّدة (بما فيها رموز الاستدلال)
max_tokens	integer	لا	اسم قديم مكافئ لـ max_completion_tokens، لا يزال مقبولًا
stop	string / array	لا	حتى 4 تسلسلات إيقاف
n	integer	لا	عدد الخيارات المولّدة. الافتراضي 1
presence_penalty	number	لا	‏-2.0–2.0. القيم الموجبة تشجّع على مواضيع جديدة
frequency_penalty	number	لا	‏-2.0–2.0. القيم الموجبة تقلّل التكرار
logprobs / top_logprobs	boolean / integer	لا	إعادة الاحتمالات اللوغاريتمية للرموز
response_format	object	لا	‏{"type":"json_object"} أو {"type":"json_schema","json_schema":{...}} للمخرجات المهيكلة
seed	integer	لا	أخذ عينات حتمي بأفضل جهد ممكن
tools	array	لا	تعريفات الدوال التي يجوز للنموذج استدعاؤها (حتى 128)
tool_choice	string / object	لا	‏none / auto / required أو فرض دالة محددة
parallel_tool_calls	boolean	لا	السماح باستدعاء الدوال بالتوازي. الافتراضي true
reasoning_effort	string	لا	لنماذج الاستدلال: low / medium / high
user	string	لا	معرّف المستخدم النهائي لمراقبة إساءة الاستخدام

📥 حقول الاستجابة

الحقل	النوع	الوصف
id	string	المعرّف الفريد للاستجابة
object	string	‏chat.completion، أو chat.completion.chunk عند التدفق
created	integer	الطابع الزمني (Unix) للإنشاء
model	string	النموذج المستخدم
choices	array	الخيارات المولّدة. يحتوي كل خيار على index وmessage ‏(role وcontent وtool_calls وrefusal) وfinish_reason
choices[].finish_reason	string	‏stop (نهاية طبيعية)، length (بلوغ حد الرموز)، tool_calls (استدعى النموذج أداة)، content_filter
usage	object	‏prompt_tokens وcompletion_tokens وtotal_tokens، مع تفاصيل إضافية (cached_tokens وreasoning_tokens وغيرها)