Skip to main content
تدعم واجهة برمجة تطبيقات OpenAI لتوليد الصور حاليًا عدة نماذج لتوليد الصور، بما في ذلك النموذج الكلاسيكي dall-e-3، ونموذج gpt-image-1 الذي يمتاز بقدرة أعلى على عرض النصوص، والجيل الأحدث gpt-image-2، بالإضافة إلى سلسلة النماذج nano-banana / nano-banana-2 / nano-banana-pro التي يتم الوصول إليها عبر نفس الواجهة. جميع هذه النماذج قادرة على توليد صور عالية الجودة بناءً على وصف نصي. تتناول هذه الوثيقة بشكل رئيسي كيفية استخدام واجهة برمجة تطبيقات OpenAI لتوليد الصور، والتي تتيح لنا استخدام وظائف توليد الصور من سلسلة OpenAI بسهولة.

عملية الطلب

لاستخدام واجهة برمجة تطبيقات OpenAI لتوليد الصور، يمكنك أولاً زيارة صفحة OpenAI Images Generations API والنقر على زر “Acquire” للحصول على بيانات الاعتماد اللازمة للطلب: إذا لم تكن قد سجلت الدخول أو لم تقم بالتسجيل، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول حيث يمكنك التسجيل وتسجيل الدخول، وبعدها ستعود تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، ستحصل على حصة مجانية يمكن استخدامها مجانًا مع هذه الواجهة.

نموذج GPT-Image-2

gpt-image-2 هو نموذج توليد الصور الجديد من OpenAI، ويتميز بتحسينات واضحة مقارنة بـ dall-e-3 و gpt-image-1 في الجوانب التالية:
  • قدرة أعلى على اتباع التعليمات: قادر على فهم التعليمات الهيكلية المعقدة مثل التكوين، العد، والعلاقات الموضعية بدقة.
  • عرض نصوص أوضح: في المشاهد مثل الملصقات، القوائم، الرسوم المعلوماتية، والشعارات، تظهر النصوص الإنجليزية والأرقام بشكل واضح دون تشويش.
  • تنوع أكبر في التعبير عن الأسلوب: يدعم بشكل أصلي أنماطًا متعددة مثل الصور السينمائية، الملصقات القديمة، الرسوم التوضيحية للأطفال، تصوير المنتجات، والرسوم المعلوماتية.
  • دعم أصلي لأبعاد متعددة ودقة عالية: يغطي 5 نسب (1:1، 4:3، 3:4، 16:9، 9:16) مع 3 مستويات دقة (1K / 2K / 4K).
طريقة الاستدعاء مماثلة تمامًا للنماذج الأخرى، فقط قم بتعيين حقل model إلى gpt-image-2. الرابط url في النتيجة هو رابط صورة مستضاف بشكل دائم على platform.cdn.xhuoapi.ai، ويمكن فتحه مباشرة في المتصفح أو تضمينه في صفحات الويب.

القيم المدعومة لحقل size ومستويات التسعير

gpt-image-2 يتحقق فقط من تنسيق size، طالما أنه ليس auto أو سلسلة فارغة، يجب أن يكون مطابقًا للنمط WIDTHxHEIGHT (مثل 1024x1024، 2048x1152، 800x600)، وأي شكل آخر سيُرجع خطأ 400. التسعير مقسم إلى مستويين فقط:
  • السعر القياسي 1K: الإدخال هو أي من أحجام 1K الموصى بها في الجدول أدناه، أو أسماء مستعارة شائعة للإخراج 1K من المصدر الأعلى (1254x1254، 1672x941، 941x1672 — هذه هي الأحجام الفعلية التي يعيدها المصدر الأعلى ضمن فئة 1K، وستُحسب بالسعر 1K عند إعادة استخدامها).
  • المستويات الأخرى (1.5×): أي حجم غير مدرج ضمن مجموعة 1K المذكورة أعلاه، بما في ذلك إعدادات 2K / 4K الموصى بها في الجدول، وأي حجم مخصص يتم تمريره.
القيود الصارمة على الأحجام المخصصة من المصدر الأعلى: العرض والارتفاع يجب أن يكونا من مضاعفات 16، والجانب الأطول ≤ 3840، وإجمالي عدد البكسلات ≤ 8,294,400. الأحجام التي تتجاوز هذه الحدود سترفض من المصدر الأعلى مع استجابة 4xx.
يمكنك أيضًا تمرير size: "auto" أو حذف حقل size، في هذه الحالة يختار النموذج الحجم الافتراضي تلقائيًا ويتم احتساب السعر كسعر 1K. في فئة 1K، لا يضمن المصدر الأعلى تطابقًا دقيقًا للبكسلات — قد ترسل 1024x1024 وتحصل على 1254x1254 مع الحفاظ على النسبة. إذا أعدت تمرير هذا الحجم كـ size، سيُحسب السعر كـ 1K. عادةً ما تستغرق استدعاءات 4K من 4 إلى 8 دقائق، يُنصح باستخدام آلية callback_url للرد غير المتزامن.
حول معامل n gpt-image-2 حاليًا لا يدعم n > 1: سيتم تجاهل هذا المعامل صامتًا، بغض النظر عن القيمة (n=1 أو n=10)، ستُرجع كل طلب صورة واحدة فقط ويتم احتساب السعر لصورة واحدة. إذا كنت بحاجة إلى عدة صور، يرجى إرسال طلبات متزامنة متعددة (يفضل مع prompt أو seed مختلفة لتجنب التشابه الكبير). هذا القيد ينطبق أيضًا على gpt-image-1 / gpt-image-1.5، وnano-banana / nano-banana-2 / nano-banana-pro. النموذج الوحيد الذي يدعم n > 1 أصليًا هو dall-e-2؛ بينما dall-e-3 يدعم فقط n = 1.
فيما يلي عدة أمثلة حقيقية من زوايا مختلفة لتوضيح قدرات gpt-image-2.

المشهد الأول: صورة سينمائية شخصية

يمكن استخدام مصطلحات سينمائية في الوصف (مثل فيلم 35 مم، عمق ميدان ضحل، أضواء النيون) للتحكم الدقيق في الجو والملمس. مثال استدعاء Python:
النتيجة:
الصورة المولدة:

المشهد الثاني: ملصق سفر قديم (مع عرض نصوص)

يُظهر gpt-image-2 أداءً مستقرًا في تنسيق النصوص والخطوط، مما يجعله مناسبًا لتوليد الملصقات والقوائم وبطاقات التهنئة التي تحتوي على نصوص.
الصورة المرتبطة بالرابط url في النتيجة:

يمكن ملاحظة أن النموذج أعاد بدقة أسلوب ملصقات Art Deco، وتم عرض النصوص AMALFI و ITALIA 1958 بوضوح وصحة.

المشهد الثالث: تكوين معقد وعدّ

الوصف التالي لاختبار قدرة النموذج على اتباع تعليمات “الكمية” و”الموقع” الهيكلية.
الصورة المولدة:

يمكن ملاحظة أن عدد الكتب (1 / 3 / 7) على الأرفف الثلاثة مطابق تمامًا للوصف، وهو أمر كان من الصعب تحقيقه بثبات في عصر dall-e-3.

المشهد الرابع: أسلوب الرسوم التوضيحية (أفقي)

بتحديد الوسيط الفني والكلمات المفتاحية للمزاج، يمكن توجيه النموذج لإنتاج رسوم توضيحية بأسلوب معين.
الرسوم التوضيحية الأفقية المولدة:

الرد غير المتزامن والاستدعاء العكسي

عادةً ما تستغرق استدعاءات gpt-image-2 من 60 إلى 90 ثانية. إذا كنت لا ترغب في إبقاء الاتصال مفتوحًا لفترة طويلة، يمكنك استخدام آلية callback_url للرد غير المتزامن التي سيتم شرحها لاحقًا، وطريقة الاستدعاء مماثلة للنماذج الأخرى.

سلسلة نماذج Nano Banana

سلسلة nano-banana هي نماذج توليد صور مبنية على Gemini، وتم دمجها عبر نفس واجهة /openai/images/generations، ولا حاجة لتغيير نقطة النهاية، فقط قم بتغيير قيمة model إلى أي من النماذج في الجدول التالي.
مهم: نطاق دعم المعاملات Nano Banana متصل عبر طبقة توافق مع بروتوكول OpenAI، ويدعم فقط المعاملات التالية مقارنة بـ gpt-image-*: model، prompt، size.
  • يتم تحويل size إلى aspect_ratio داخليًا وفق الجدول التالي، والأحجام غير المدرجة تتحول إلى 1:1:
    • 1024x1024 / 512x512 / 256x2561:1
    • 1792x102416:9
    • 1024x17929:16
  • لا يدعم المعاملات n، quality، style، response_format، background، output_format؛ وإذا تم تمريرها سيتم تجاهلها.
  • هيكل الرد يتبع تنسيق OpenAI (data[].url)، لكن created ثابت على 0، ولا يتم إرجاع b64_json، وrevised_prompt دائمًا يساوي prompt الأصلي.

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

النتيجة:
يمكن الوصول إلى الصورة المولدة مباشرة عبر الرابط url:

الترقية إلى النموذج الرائد nano-banana-pro

يكفي تغيير model إلى nano-banana-pro مع بقاء باقي المعاملات كما هي:
مثال النتيجة:

الرد غير المتزامن

آلية callback_url للرد غير المتزامن فعالة أيضًا مع nano-banana، وطريقة الاستدعاء مماثلة للنماذج الأخرى، راجع القسم الرد غير المتزامن أدناه.

الاستخدام الأساسي

بعد ذلك يمكنك ملء الحقول المناسبة في الواجهة كما في الصورة:

عند استخدام الواجهة لأول مرة، نحتاج إلى ملء ثلاثة حقول على الأقل: الأول هو authorization، يمكن اختياره مباشرة من القائمة المنسدلة. الحقل الثاني هو model، وهو اختيار نموذج OpenAI DALL-E الرسمي، لدينا نموذج واحد رئيسي، يمكن الاطلاع على التفاصيل في قائمة النماذج المتاحة. الحقل الأخير هو prompt، وهو وصف النص الذي نريد توليد الصورة بناءً عليه. يمكنك أيضًا ملاحظة وجود كود الاستدعاء على الجانب الأيمن، يمكنك نسخه وتشغيله مباشرة، أو الضغط على زر “Try” للاختبار.

مثال استدعاء Python:
النتيجة:
النتيجة تحتوي على عدة حقول:
  • created: معرف فريد لمهمة توليد الصورة.
  • data: يحتوي على معلومات نتائج توليد الصورة.
داخل data توجد معلومات مفصلة عن الصورة المولدة، والرابط url هو رابط تفصيلي للصورة كما هو موضح في الصورة التالية:

معامل جودة الصورة quality

سنشرح الآن كيفية ضبط بعض المعاملات التفصيلية لنتائج توليد الصور، منها معامل جودة الصورة quality الذي يحتوي على خيارين: الأول standard لتوليد صورة بجودة قياسية، والثاني hd لإنشاء صورة بتفاصيل أدق واتساق أكبر. إعداد جودة الصورة إلى standard كما في الصورة:

يمكنك أيضًا ملاحظة وجود كود الاستدعاء على الجانب الأيمن، يمكنك نسخه وتشغيله مباشرة، أو الضغط على زر “Try” للاختبار.

مثال استدعاء Python:
النتيجة:
النتيجة مماثلة للاستخدام الأساسي، والصورة المولدة بجودة standard كما في الصورة:

بنفس الطريقة، عند تعيين جودة الصورة إلى hd، ستحصل على صورة كما في الصورة التالية:

يمكن ملاحظة أن جودة hd تنتج صورة بتفاصيل أدق واتساق أكبر مقارنة بـ standard.

معامل حجم الصورة size

يمكننا أيضًا ضبط حجم الصورة المولدة. مثلاً، تعيين حجم الصورة إلى 1024 * 1024 كما في الصورة:

يمكنك أيضًا ملاحظة وجود كود الاستدعاء على الجانب الأيمن، يمكنك نسخه وتشغيله مباشرة، أو الضغط على زر “Try” للاختبار.

مثال استدعاء Python:
النتيجة:
النتيجة مماثلة للاستخدام الأساسي، والصورة بحجم 1024 * 1024 كما في الصورة:

بنفس الطريقة، عند تعيين حجم الصورة إلى 1792 * 1024، ستحصل على صورة كما في الصورة التالية: يمكن ملاحظة الفرق الواضح في حجم الصورة، ويمكنك ضبط المزيد من الأحجام، راجع الوثائق الرسمية لمزيد من التفاصيل.

معامل نمط الصورة style

معامل نمط الصورة style يحتوي على خيارين: الأول vivid لتوليد صور أكثر حيوية، والثاني natural لتوليد صور أكثر طبيعية. مثلاً، تعيين نمط الصورة إلى vivid كما في الصورة:

يمكنك أيضًا ملاحظة وجود كود الاستدعاء على الجانب الأيمن، يمكنك نسخه وتشغيله مباشرة، أو الضغط على زر “Try” للاختبار.

مثال استدعاء Python:
النتيجة:
النتيجة مماثلة للاستخدام الأساسي، والصورة بنمط vivid كما في الصورة:

بنفس الطريقة، عند تعيين نمط الصورة إلى natural، ستحصل على صورة كما في الصورة التالية:

يمكن ملاحظة أن vivid ينتج صورًا أكثر حيوية وواقعية مقارنة بـ natural.

معامل تنسيق رابط الصورة response_format

أخيرًا، معامل تنسيق رابط الصورة response_format يحتوي على خيارين: الأول b64_json لترميز رابط الصورة بصيغة Base64، والثاني url وهو رابط الصورة العادي الذي يمكن عرضه مباشرة. مثلاً، تعيين تنسيق الرابط إلى url كما في الصورة:

يمكنك أيضًا ملاحظة وجود كود الاستدعاء على الجانب الأيمن، يمكنك نسخه وتشغيله مباشرة، أو الضغط على زر “Try” للاختبار.

مثال استدعاء Python:
النتيجة:
النتيجة مماثلة للاستخدام الأساسي، ورابط الصورة بنمط url هو رابط الصورة ويمكن عرض الصورة كما في الصورة التالية:

بنفس الطريقة، عند تعيين تنسيق الرابط إلى b64_json، ستحصل على نتيجة تحتوي على رابط الصورة مشفرًا بصيغة Base64، كما في المثال التالي:

الرد غير المتزامن

نظرًا لأن توليد الصور عبر واجهة OpenAI قد يستغرق وقتًا نسبيًا طويلاً، فإن إبقاء طلب HTTP مفتوحًا لفترة طويلة يؤدي إلى استهلاك موارد النظام، لذا توفر هذه الواجهة دعمًا للرد غير المتزامن. العملية كالتالي: عند إرسال الطلب، تحدد حقلًا إضافيًا callback_url، ثم تعيد الواجهة فورًا نتيجة تحتوي على حقل task_id يمثل معرف المهمة الحالية. عند الانتهاء من توليد الصورة، ترسل الواجهة النتيجة عبر طلب POST بصيغة JSON إلى عنوان callback_url المحدد، متضمنةً أيضًا حقل task_id لربط النتيجة بالمهمة. فيما يلي مثال عملي. أولًا، يجب أن يكون Webhook هو خدمة تستقبل طلبات HTTP، ويجب على المطور استبدالها بعنوان خادم HTTP خاص به. لأغراض العرض، نستخدم موقع Webhook عام https://webhook.site/، عند فتح الموقع ستحصل على عنوان Webhook كما في الصورة: انسخ هذا العنوان، ليكون عنوان Webhook للاستخدام، في المثال هو https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. بعدها، نحدد حقل callback_url إلى عنوان Webhook السابق، مع ملء باقي المعاملات كما في الكود التالي:
عند التشغيل، ستحصل فورًا على نتيجة مثل:
بعد فترة قصيرة، يمكنك مراقبة نتائج توليد الصورة على عنوان Webhook، وستكون المحتويات كما يلي:
يمكن ملاحظة وجود حقل task_id، وdata تحتوي على نفس نتائج توليد الصورة كما في الاستدعاء المتزامن، مما يتيح ربط النتائج بالمهمة عبر task_id.

معالجة الأخطاء

عند استدعاء الواجهة، إذا حدث خطأ، ستُرجع الواجهة رمز الخطأ والمعلومات المناسبة، مثل:
  • 400 token_mismatched: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.
  • 400 api_not_implemented: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.
  • 401 invalid_token: غير مصرح، رمز التفويض مفقود أو غير صالح.
  • 429 too_many_requests: عدد الطلبات كبير جدًا، تجاوزت الحد المسموح.
  • 500 api_error: خطأ داخلي في الخادم.

مثال على استجابة الخطأ

الخلاصة

من خلال هذه الوثيقة، أصبحت تعرف كيفية استخدام واجهة برمجة تطبيقات OpenAI لتوليد الصور بسهولة باستخدام نموذج DALL-E الرسمي من OpenAI. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأفضل لهذه الواجهة. في حال وجود أي استفسارات، يرجى التواصل مع فريق الدعم الفني لدينا.