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

تُستخدم هذه الواجهة لإرسال مطالبة إلى النموذج (تتضمن نصًا أو صورة)، وسيُرجع النموذج ردًا واحدًا أو أكثر من الردود المُولدة. هذه الواجهة مناسبة بشكل خاص للنماذج التي تدعم الإدخال متعدد الوسائط (مثل معالجة الصور، وتحسينها، والتعرّف عليها وإنشاء محتوى منها)، مثل gpt-4o-image-vip.

معلومات الواجهة

عنوان الواجهة: https://api.codingplanx.ai/v1/chat/completions
طريقة الطلب: POST
نوع المحتوى: application/json
نوع الاستجابة: application/json

ترويسات الطلب (Headers)

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

معاملات الطلب (Body)

جسم الطلب هو كائن JSON يحتوي على الحقول التالية:

اسم المعامل	النوع	مطلوب	القيمة الافتراضية	الوصف
model	String	نعم	-	معرّف النموذج المطلوب استخدامه. مثال: `gpt-4o-image-vip`.
messages	Array	نعم	-	قائمة رسائل المحادثة. يحتوي كل كائن على `role` ‏(user/assistant/system) و`content`. يمكن أن يكون `content` سلسلة نصية، أو مصفوفة من الكائنات التي تحتوي على النوع ورابط الصورة.
tools	Array	نعم	-	قائمة الأدوات التي يمكن للنموذج استدعاؤها. حاليًا يتم دعم الدوال فقط.
tool_choice	Object	نعم	`none`	يحدد أي دالة يجب على النموذج استدعاؤها. القيمة `none` تعني عدم الاستدعاء، و`auto` تعني الاختيار التلقائي.
temperature	Number	لا	1	درجة حرارة أخذ العينات (0-2). كلما زادت كانت النتائج أكثر عشوائية، وكلما انخفضت كانت أكثر تركيزًا.
top_p	Number	لا	1	أخذ العينات بالنواة. يتم النظر فقط في الرموز التي تقع ضمن أعلى كتلة احتمالية P. يُنصح بضبطه بدلًا من `temperature` وليس معه في العادة.
n	Integer	لا	1	عدد خيارات الإكمال التي سيتم توليدها لكل إدخال.
stream	Boolean	لا	`false`	ما إذا كان سيتم الإرسال بشكل متدفق. الواجهة الحالية مُعرّفة كغير متدفقة.
max_tokens	Integer	لا	inf	الحد الأقصى لعدد الرموز التي سيتم توليدها.
stop	String/Array	لا	null	رموز التوقف. ستتوقف الواجهة عن توليد المزيد من الرموز عند الوصول إليها.
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	لا	-	معرّف فريد يمثّل المستخدم النهائي، ويُستخدم لمراقبة إساءة الاستخدام.
seen	Integer	لا	-	(إصدار تجريبي) يحدد قيمة البذرة لمحاولة تحقيق أخذ عينات حتمي قدر الإمكان.

معاملات الاستجابة

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

أمثلة

مثال على الطلب (تحسين/إنشاء الصور)

{
    "model": "gpt-4o-image-vip",
    "messages": [
      {
            "role": "user",
            "content": [
                {"type": "text", "text": "قم بتحسين هذه الصورة، وأضف عبارة أحب الصين، بنسبة أبعاد [4:3]"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://lsky.zhongzhuan.chat/i/2024/10/17/6711068a14527.png"
                    }
                }
            ]
        }
    ],
    "tools": [],
    "tool_choice": "none"
}

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

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "حسنًا، تمت معالجة الصورة لك. يمكنك الاطلاع على النتيجة المُولدة التالية: [رابط/وصف الصورة]"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

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

س: لماذا يحدث خطأ عند استخدام response_format: { "type": "json_object" }؟
ج: عند استخدام وضع JSON، يجب عليك توضيح أن على النموذج أن يُنتج JSON صراحةً داخل messages (على سبيل المثال: إضافة توجيه في رسالة النظام مثل "يرجى الرد بصيغة JSON"). وإلا فقد ينتج النموذج محتوى غير بصيغة JSON، مما قد يؤدي إلى حلقة لا نهائية أو إلى حدوث خطأ.

س: كيف يمكنني ضمان أن تكون النتيجة نفسها في كل مرة؟
ج: رغم أن نماذج الذكاء الاصطناعي تتسم بالعشوائية بطبيعتها، يمكنك محاولة ضبط المعامل seen (seed) مع إبقاء temperature على 0، وكذلك متابعة الحقل system_fingerprint في الاستجابة لمراقبة ما إذا كانت بيئة التشغيل الخلفية قد تغيّرت.

س: ما الحجم المناسب لإعداد max_tokens؟
ج: يعتمد ذلك على سيناريو الاستخدام. بالنسبة لوصف الصور القصير، غالبًا ما تكون 100-300 كافية؛ أما إذا كنت تحتاج إلى تحليل مفصل أو إنشاء نصوص طويلة، فيُنصح بضبطها على 1000 أو أكثر. يرجى الانتباه إلى أن مجموع رموز الإدخال (بما في ذلك الصور) ورموز الإخراج لا يمكن أن يتجاوز حد السياق الخاص بالنموذج.

س: كيف أتعامل مع إدخال الصور؟
ج: داخل content في messages، استخدم type: "image_url". يُنصح حاليًا باستخدام روابط صور HTTPS عامة يمكن الوصول إليها عبر الإنترنت.

س: هل tools وtool_choice مطلوبان؟
ج: وفقًا لتعريف هذه الواجهة، تم وضع هذين الحقلين على أنهما مطلوبان. إذا لم تكن بحاجة إلى استدعاء أداة محددة، فقم بتعيين tools إلى مصفوفة فارغة []، وعيّن tool_choice إلى "none"۔