dall-e-2، gpt-image-1، وأحدثها gpt-image-2، بالإضافة إلى نماذج سلسلة nano-banana / nano-banana-2 / nano-banana-pro التي يتم الوصول إليها عبر نفس الواجهة.
تشرح هذه الوثيقة بشكل رئيسي كيفية استخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور، والتي تمكننا من استخدام وظائف تعديل الصور الرسمية من OpenAI بسهولة.
عملية الطلب
لاستخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور، يمكنك أولاً زيارة صفحة OpenAI Images Edits API والنقر على زر “Acquire” للحصول على بيانات الاعتماد المطلوبة للطلب: إذا لم تكن مسجلاً أو مسجلاً دخولك، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول للتسجيل أو الدخول، وبعد ذلك ستعود تلقائيًا إلى الصفحة الحالية. عند الطلب لأول مرة، ستحصل على رصيد مجاني يمكن استخدامه مجانًا لهذه الواجهة.نموذج GPT-Image-2
يقدم نموذجgpt-image-2 تحسينات واضحة مقارنة بـ gpt-image-1 في سيناريوهات تعديل الصور:
- ثبات أكبر في الهيكل: عند تغيير الجلد، الألوان، أو الخلفية، لا يتم كسر تخطيط أو تركيب الصورة الأصلية تقريبًا.
- دقة أفضل في الاحتفاظ بالنصوص: الصور التي تحتوي على نصوص مثل الإنفوغرافيك، الملصقات، والقوائم تظل النصوص فيها واضحة وقابلة للقراءة بعد التعديل.
- دعم تحميل URL مباشرة: بالإضافة إلى التحميل التقليدي للملفات باستخدام
multipart/form-data، يدعمgpt-image-2أيضًا تمرير رابط الصورة بصيغة JSON، مما يلغي الحاجة لتحميل الصورة محليًا، وهو مناسب جدًا للتكامل في سير عمل الخادم. - دعم إعادة الرسم بدقة عالية: يمكن تمرير صورة أصلية بدقة 1K، وطلب إخراج بدقة 2K أو 4K عبر معامل
size، حيث يقوم النموذج بالتكبير أثناء عملية التعديل.
القيم المدعومة لمعامل size
تتطابق قيود معامل size في واجهة التعديل مع واجهة التوليد تمامًا — حيث يقبل gpt-image-2 القيم auto، فارغة، أو بصيغة WIDTHxHEIGHT فقط، وأي شكل آخر يعيد خطأ 400. يتم احتساب التكلفة لكل صورة موحدة بغض النظر عن دقة الصورة الأصلية أو قيمة size المطلوبة (1K / 2K / 4K / مخصصة).
تطبق القيود العليا على الأبعاد المخصصة أيضًا: العرض والارتفاع يجب أن يكونا من مضاعفات 16، والجانب الأطول ≤ 3840، وإجمالي عدد البكسلات ≤ 8,294,400.
على سبيل المثال: إذا كانت الصورة الأصلية1024x1024وتم تمريرsizeكـ2048x2048، سيعيد النموذج صورة بدقة 2K مع تطبيق التعديلات؛ وإذا كانت3840x2160، فسيتم إخراج صورة 4K أفقية؛ وإذا كانتautoأو تم حذفها، يختار النموذج الحجم تلقائيًا. التكلفة في الثلاث حالات متساوية.
حول معاملفيما يلي مثالان واقعيان من زوايا مختلفة لتجربة قدرات التعديل فيnلا يدعم نموذجgpt-image-2حاليًا تعديل الصور معn > 1؛ سيتم تجاهل هذا المعامل بصمت، بغض النظر عن القيمة المرسلة سواءn=1أوn=10، ستُعاد صورة واحدة فقط لكل طلب ويتم احتساب التكلفة على صورة واحدة فقط. إذا كنت بحاجة إلى عدة نتائج، يرجى إرسال طلبات متزامنة متعددة بنفسك. ينطبق هذا القيد أيضًا علىgpt-image-1/gpt-image-1.5، وnano-banana/nano-banana-2/nano-banana-pro. أماdall-e-2فهو النموذج الوحيد الذي يدعمn > 1بشكل أصلي.
gpt-image-2.
طريقة الاتصال الأولى: JSON + رابط الصورة (موصى بها)
إرسال الطلب مباشرة بصيغةapplication/json، مع ملء حقل image برابط صورة، حيث يقوم النموذج بجلب الصورة وتعديلها وفقًا لـ prompt.
على سبيل المثال، هذه الصورة الأصلية هي صورة علمية تم إنشاؤها بواسطة gpt-image-2:
نرغب في تحويلها إلى “الوضع الليلي”. يمكننا الاتصال هكذا:
ملاحظة: يدعم حقلimageأيضًا تمرير مصفوفة، مثل"image": ["url1", "url2", "url3"]، حتى 16 صورة مرجعية في نفس الوقت، ليأخذ النموذج في الاعتبار عدة صور أثناء التعديل.
طريقة الاتصال الثانية: JSON + عدة صور مرجعية
يدعمgpt-image-2 استخدام عدة صور مرجعية لإنشاء النتيجة النهائية، مثل دمج عدة صور منتجات في سلة هدايا واحدة:
سيناريو المثال: تغيير الأسلوب مع الحفاظ على الهيكل
مثال آخر، استبدال رف كتب خشبي بآخر عائم حديث مع الحفاظ بدقة على عدد وترتيب الكتب في كل طبقة. الصورة الأصلية (رف كتب خشبي مولد بواسطةgpt-image-2):
الطلب:
task_id: e9544dba-727e-44a2-81e1-223d49869380):
يمكن ملاحظة أن الأسلوب والبيئة تم استبدالهما بالكامل حسب التعليمات، مع الحفاظ الصارم على عدد الكتب في كل طبقة (1 / 3 / 7)، وإضافة نبتة عصارية صغيرة كما هو مطلوب.
طريقة الاتصال الثالثة: multipart/form-data (متوافق مع OpenAI SDK)
إذا كنت تستخدم SDK الرسمي لـ OpenAI بلغة Python، فإن طريقة التحميل باستخدامmultipart/form-data لا تزال صالحة، فقط قم بتغيير model إلى gpt-image-2:
OPENAI_BASE_URL إلى https://api.acedata.cloud/openai، وOPENAI_API_KEY إلى التوكن الذي حصلت عليه:
نماذج سلسلة Nano Banana
تدعم سلسلةnano-banana أيضًا التعديل عبر /openai/images/edits، فقط قم بتغيير model إلى أي نموذج من الجدول التالي:
مهم: نطاق دعم المعاملات تتصل Nano Banana ببروتوكول OpenAI عبر طبقة توافق، وتدعم فقط المعاملات التالية:model،prompt،image.
- يمكن رفع
imageعبرmultipart/form-data(يتم تحويله داخليًا إلىdata:<mime>;base64,...وإرساله للأعلى)، أو تمرير رابط الصورة مباشرة كسلسلة نصية في حقل النموذج.- لا تدعم المعاملات
mask،n،size،response_format؛ سيتم تجاهلها إذا تم تمريرها.- تتبع النتيجة تنسيق OpenAI (
data[].url)، لكنcreatedثابت على0، ولا يتم إرجاعb64_json، وrevised_promptيساوي دائمًاpromptالأصلي.
الاتصال عبر نموذج + رابط صورة
الاتصال عبر نموذج + ملف محلي
الاستدعاء غير المتزامن (Callback)
يدعم نموذج nano-banana أيضًا آلية الاستدعاء غير المتزامنcallback_url، وتتم العملية بنفس طريقة النماذج الأخرى، راجع القسم التالي الاستدعاء غير المتزامن.
الاستخدام الأساسي
يمكنك الآن استخدام الكود لإجراء الطلب، فيما يلي مثال باستخدام CURL:authorization، يمكن اختياره من القائمة المنسدلة. الثاني هو model، وهو اختيار نموذج OpenAI الرسمي، ويوجد لدينا نموذج واحد رئيسي، يمكن الاطلاع على التفاصيل في قسم النماذج. الثالث هو prompt، وهو النص الذي يصف الصورة المراد إنشاؤها. الأخير هو image، وهو مسار الصورة التي نريد تعديلها، كما في الصورة التالية:
كود Python المكافئ لنفس الطلب:
OPENAI_BASE_URL إلى https://api.acedata.cloud/openai، وOPENAI_API_KEY إلى التوكن الذي حصلت عليه من authorization. على نظام Mac OS يمكن تعيينهما بالأوامر التالية:
gift-basket.png تم إنشاؤها في الدليل الحالي، والنتيجة كما يلي:
بهذا نكون قد أكملنا عملية تعديل الصورة. حاليًا، تدعم واجهة Edits ثلاثة نماذج: dall-e-2، gpt-image-1، وgpt-image-2، حيث يُنصح باستخدام gpt-image-2 كما هو موضح في قسم نموذج GPT-Image-2.
الاستدعاء غير المتزامن (Callback)
نظرًا لأن تعديل الصور عبر OpenAI Images Edits API قد يستغرق وقتًا نسبيًا طويلاً، وإذا لم يستجب API لفترة طويلة، فإن طلب HTTP يبقى متصلًا مما يستهلك موارد النظام، لذلك توفر هذه الواجهة دعمًا للاستدعاء غير المتزامن. العملية الكاملة هي: عند إرسال الطلب، يتم تمرير حقل إضافيcallback_url، وبعد إرسال الطلب، يعيد API فورًا نتيجة تحتوي على task_id يمثل معرف المهمة. عند الانتهاء من تعديل الصورة، يتم إرسال النتيجة إلى callback_url المحدد عبر POST بصيغة JSON، مع تضمين task_id لربط النتيجة بالمهمة.
فيما يلي مثال عملي.
أولًا، يجب أن يكون Webhook هو خدمة تستقبل طلبات HTTP، ويجب على المطور استبدالها بعنوان خادم HTTP الخاص به. للتجربة، يمكن استخدام موقع ويب Webhook عام مثل https://webhook.site/، حيث تحصل على عنوان Webhook كما في الصورة:
انسخ هذا العنوان، مثلاً https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab، واستخدمه كـ Webhook.
بعدها، يمكن تعيين حقل callback_url إلى عنوان Webhook، مع ملء باقي الحقول كما في المثال التالي:
task_id، وحقل data يحتوي على نفس نتيجة تعديل الصورة كما في الاستدعاء المتزامن، مما يتيح ربط المهمة بالنتيجة عبر task_id.
معالجة الأخطاء
عند استدعاء API، إذا حدث خطأ، ستعيد الواجهة رمز الخطأ والمعلومات المناسبة، مثل:400 token_mismatched: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.400 api_not_implemented: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.401 invalid_token: غير مصرح، توكن التفويض مفقود أو غير صالح.429 too_many_requests: عدد الطلبات كبير جدًا، تجاوزت الحد المسموح.500 api_error: خطأ داخلي في الخادم، حدث خطأ ما في الخادم.

