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 الموصى بها في الجدول، وأي حجم مخصص يتم تمريره.
| النسبة | 1K (السعر القياسي) | 2K الموصى به (×1.5) | 4K الموصى به (×1.5) |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 4:3 | 1536x1024 | 2048x1536 | 3264x2448 |
| 3:4 | 1024x1536 | 1536x2048 | 2448x3264 |
| 16:9 | 1792x1024 | 2048x1152 | 3840x2160 |
| 9:16 | 1024x1792 | 1152x2048 | 2160x3840 |
يمكنك أيضًا تمريرsize: "auto"أو حذف حقلsize، في هذه الحالة يختار النموذج الحجم الافتراضي تلقائيًا ويتم احتساب السعر كسعر 1K. في فئة 1K، لا يضمن المصدر الأعلى تطابقًا دقيقًا للبكسلات — قد ترسل1024x1024وتحصل على1254x1254مع الحفاظ على النسبة. إذا أعدت تمرير هذا الحجم كـsize، سيُحسب السعر كـ 1K. عادةً ما تستغرق استدعاءات 4K من 4 إلى 8 دقائق، يُنصح باستخدام آليةcallback_urlللرد غير المتزامن.
حول معاملفيما يلي عدة أمثلة حقيقية من زوايا مختلفة لتوضيح قدراتngpt-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 في النتيجة:

AMALFI و ITALIA 1958 بوضوح وصحة.
المشهد الثالث: تكوين معقد وعدّ
الوصف التالي لاختبار قدرة النموذج على اتباع تعليمات “الكمية” و”الموقع” الهيكلية.
dall-e-3.
المشهد الرابع: أسلوب الرسوم التوضيحية (أفقي)
بتحديد الوسيط الفني والكلمات المفتاحية للمزاج، يمكن توجيه النموذج لإنتاج رسوم توضيحية بأسلوب معين.
الرد غير المتزامن والاستدعاء العكسي
عادةً ما تستغرق استدعاءاتgpt-image-2 من 60 إلى 90 ثانية. إذا كنت لا ترغب في إبقاء الاتصال مفتوحًا لفترة طويلة، يمكنك استخدام آلية callback_url للرد غير المتزامن التي سيتم شرحها لاحقًا، وطريقة الاستدعاء مماثلة للنماذج الأخرى.
سلسلة نماذج Nano Banana
سلسلةnano-banana هي نماذج توليد صور مبنية على Gemini، وتم دمجها عبر نفس واجهة /openai/images/generations، ولا حاجة لتغيير نقطة النهاية، فقط قم بتغيير قيمة model إلى أي من النماذج في الجدول التالي.
| النموذج | التكلفة (Credits / طلب) | السيناريوهات المناسبة |
|---|---|---|
nano-banana | 0.14 | توليد صور عادي، الأسرع والأقل تكلفة |
nano-banana-2 | 0.28 | جودة وتفاصيل محسنة بوضوح |
nano-banana-pro | 0.35 | الطراز الرائد في السلسلة، أفضل في التكوين، التفاصيل، والنصوص |
مهم: نطاق دعم المعاملات Nano Banana متصل عبر طبقة توافق مع بروتوكول OpenAI، ويدعم فقط المعاملات التالية مقارنة بـgpt-image-*:model،prompt،size.
- يتم تحويل
sizeإلىaspect_ratioداخليًا وفق الجدول التالي، والأحجام غير المدرجة تتحول إلى1:1:
1024x1024/512x512/256x256→1:11792x1024→16:91024x1792→9: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” للاختبار.

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

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


standard كما في الصورة:

hd، ستحصل على صورة كما في الصورة التالية:

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


1024 * 1024 كما في الصورة:

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


vivid كما في الصورة:

natural، ستحصل على صورة كما في الصورة التالية:

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


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 السابق، مع ملء باقي المعاملات كما في الكود التالي:
task_id، وdata تحتوي على نفس نتائج توليد الصورة كما في الاستدعاء المتزامن، مما يتيح ربط النتائج بالمهمة عبر task_id.
معالجة الأخطاء
عند استدعاء الواجهة، إذا حدث خطأ، ستُرجع الواجهة رمز الخطأ والمعلومات المناسبة، مثل:400 token_mismatched: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.400 api_not_implemented: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.401 invalid_token: غير مصرح، رمز التفويض مفقود أو غير صالح.429 too_many_requests: عدد الطلبات كبير جدًا، تجاوزت الحد المسموح.500 api_error: خطأ داخلي في الخادم.

