إنشاء إكمال دردشة مع فهم الصور (غير متدفق)

تُستخدم هذه الواجهة لإرسال مطالبات إلى النموذج تتضمن نصوصًا وصورًا، والحصول على نتيجة إكمال دردشة واحدة لكل طلب. سيقوم النموذج بإرجاع وصف مفصل أو إجابة بناءً على السياق المُدخل ومحتوى الصورة.

عنوان الواجهة: https://api.codingplanx.ai/v1/chat/completions
طريقة الطلب: POST
الحالة: تم الإصدار (Released)

رؤوس الطلب (Headers)

اسم المعامل	مطلوب	النوع	مثال القيمة	الوصف
Content-Type	نعم	String	`application/json`	تنسيق جسم الطلب
Accept	نعم	String	`application/json`	تنسيق جسم الاستجابة
Authorization	لا	String	`Bearer {{YOUR_API_KEY}}`	مفتاح API المستخدم للمصادقة

جسم الطلب (Request Body)

اسم المعامل	مطلوب	النوع	القيمة الافتراضية	الوصف
model	نعم	String	-	معرّف النموذج المراد استخدامه (مثل `gpt-4o`).
messages	نعم	Array	-	قائمة رسائل المحادثة. عند استخدام فهم الصور، يجب تمرير `content` كمصفوفة من الكائنات.
temperature	لا	Number	1	درجة حرارة أخذ العينات (0-2). كلما ارتفعت زادت العشوائية، وكلما انخفضت أصبحت النتائج أكثر ثباتًا.
top_p	لا	Number	1	احتمال أخذ العينات النووي. يُنصح بتعديل هذا الحقل أو `temperature` فقط، وليس كليهما معًا.
max_tokens	لا	Integer	inf	الحد الأقصى لعدد الـ Token التي سيتم توليدها.
n	لا	Integer	1	عدد الردود البديلة التي يتم توليدها لكل إدخال.
stream	لا	Boolean	false	ما إذا كان الإخراج سيكون متدفقًا. في هذه الواجهة تكون القيمة ثابتة `false`.
stop	لا	String/Array	null	علامات إيقاف التوليد. يدعم بحد أقصى 4 سلاسل.
presence_penalty	لا	Number	0	عقوبة الوجود (-2.0 إلى 2.0)، تزيد احتمال التطرق إلى مواضيع جديدة.
frequency_penalty	لا	Number	0	عقوبة التكرار (-2.0 إلى 2.0)، تقلل من تكرار نفس العبارات.
response_format	لا	Object	-	تحديد تنسيق الإخراج، مثل `{ "type": "json_object" }` لتفعيل وضع JSON.
user	لا	String	-	معرّف فريد للمستخدم النهائي.
tools	لا	Array	-	قائمة الأدوات التي يمكن للنموذج استدعاؤها (حاليًا يتم دعم `function` فقط).
tool_choice	لا	Object	-	التحكم في سلوك استدعاء الأدوات من قبل النموذج (`none` / `auto` / تحديد دالة معيّنة).

بنية كائن فهم الصور في `messages` (Content Array)

عند تنفيذ طلب لفهم الصور، يجب أن يحتوي messages.content على البنية التالية:

type: إما "text" أو "image_url"
text: عند كون type هو text، يتم تمرير السؤال النصي.
image_url: عند كون type هو image_url، يتم تمرير كائن بالشكل { "url": "رابط الصورة" }.

مثال الطلب (Example)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "أنت مساعد مفيد."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "ماذا يوجد في هذه الصورة؟ يرجى الوصف بالتفصيل."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://lsky.zhongzhuan.chat/i/2024/10/17/6711068a14527.png"
                    }
                }
            ]
        }
    ]
}

معاملات الاستجابة (Response Body)

اسم المعامل	النوع	الوصف
id	String	المعرّف الفريد لهذا الطلب.
object	String	نوع الكائن، وتكون قيمته الثابتة `chat.completion`.
created	Integer	طابع زمني Unix (بالثواني).
choices	Array	يحتوي على عدة خيارات من المخرجات المولدة.
└ index	Integer	فهرس الخيار.
└ message	Object	كائن الرسالة الذي يعيده النموذج (يتضمن `role` و `content`).
└ finish_reason	String	سبب توقف التوليد (مثل `stop` أو `length`).
usage	Object	إحصائيات استخدام الـ Token.
└ prompt_tokens	Integer	عدد الـ Token المستهلكة في نص الإدخال.
└ completion_tokens	Integer	عدد الـ Token المستهلكة في النتيجة المولدة.
└ total_tokens	Integer	إجمالي عدد الـ Token المستهلكة.

مثال الاستجابة (Response)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "تعرض هذه الصورة سطح مكتب مرتبًا عليه جهاز كمبيوتر محمول وكوب قهوة ونبتة عصارية صغيرة."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 45,
        "total_tokens": 165
    }
}

الأسئلة الشائعة (FAQs)

س: ما النماذج التي تدعم ميزة فهم الصور؟
ج: حاليًا يتم دعم نماذج متعددة الوسائط مثل gpt-4o و gpt-4-turbo و gpt-4-vision-preview. يُرجى التأكد من تمرير معرّف النموذج الصحيح في حقل model.

س: ما تنسيقات الصور المدعومة؟
ج: يتم دعم تنسيقات الصور الشائعة مثل PNG و JPEG و WEBP و GIF غير المتحرك.

س: هل توجد قيود على صلاحية رابط الصورة؟
ج: يجب أن يكون رابط الصورة المقدم قابلاً للوصول بشكل عام. إذا كانت الصورة مخزنة في مساحة سحابية خاصة، فيرجى أولًا إنشاء رابط وصول مؤقت موقّع أو تحويل الصورة إلى Base64 ثم تمريرها (ملاحظة: يجب أن يلتزم Base64 بالتنسيق data:image/jpeg;base64,...).

س: كيف يتم احتساب تكلفة التعرف على الصور؟
ج: يتم تحويل الصور إلى Token وفقًا لدقتها ومستوى التفاصيل فيها من أجل الفوترة. عادةً ما تستهلك الصور منخفضة الدقة عددًا ثابتًا وصغيرًا من الـ Token، بينما تُحتسب الصور عالية الدقة بناءً على عدد المقاطع بحجم 512x512.

س: ماذا أفعل إذا أردت إخراجًا متدفقًا (تأثير الكتابة التدريجية)؟
ج: يُرجى تعيين معامل الطلب stream إلى true. ولكن يُرجى ملاحظة أن هذا المستند يشرح الاستجابة غير المتدفقة، وعند استخدام الإخراج المتدفق سيتغير تنسيق البيانات إلى Server-Sent Events (SSE).

س: لماذا تم إرجاع "finish_reason": "length"؟
ج: هذا يعني أن الرد المولد وصل إلى حد max_tokens الذي قمت بتعيينه، أو أنه تجاوز نافذة السياق الخاصة بالنموذج، مما أدى إلى اقتطاع المحتوى.