خدمة تعديل الصور من OpenAI تتيح لك إرسال أي عدد من الصور والتعليمات، والحصول على الصور المعدلة. حالياً، تدعم الواجهة نماذجDocumentation Index
Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
Use this file to discover all available pages before exploring further.
dall-e-2، gpt-image-1، وأحدثها gpt-image-2، بالإضافة إلى سلسلة النماذج nano-banana / nano-banana-2 / nano-banana-pro التي يتم الوصول إليها عبر نفس الواجهة.
تقدم هذه الوثيقة شرحاً لعملية استخدام واجهة برمجة تطبيقات OpenAI Images Edits، والتي تمكننا من استخدام وظائف تعديل الصور الرسمية من OpenAI بسهولة.
عملية التقديم
لاستخدام واجهة برمجة تطبيقات OpenAI Images Edits، يمكنك أولاً الذهاب إلى صفحة 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 قيمة size إما auto، فارغة، أو بصيغة WIDTHxHEIGHT، وأي صيغة أخرى ترجع خطأ 400. التسعير مقسم إلى مستويين فقط، بغض النظر عن دقة الصورة الأصلية، ويعتمد فقط على قيمة size المطلوبة:
- السعر القياسي 1K: أي من أحجام 1K الموصى بها في الجدول أدناه، أو أسماء مستعارة شائعة 1K (مثل
1254x1254،1672x941،941x1672). - مستوى آخر (1.5×): يشمل إعدادات 2K / 4K الموصى بها في الجدول، أو أي حجم مخصص ترسله بصيغة
WIDTHxHEIGHT.
| النسبة | 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 |
على سبيل المثال: إذا كانت الصورة الأصلية1024x1024، وعند إرسالsizeبقيمة2048x2048، سيعيد النموذج رسم الصورة بدقة 2K وفقاً لتعليمات التعديل ويحسب السعر على المستوى “الآخر”؛ وعند إرسالsizeبقيمة3840x2160، ينتج صورة أفقية 4K ويحسب السعر كذلك على المستوى “الآخر”. أما عند إرسالautoأو تركه فارغاً، فيحسب السعر على المستوى القياسي 1K.
حول معاملفيما يلي مثالان حقيقيان من زوايا مختلفة لتجربة قدرات التعديل في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):

طريقة الاستدعاء الثالثة: multipart/form-data (متوافق مع OpenAI SDK)
إذا كنت تستخدم SDK الرسمي لـ OpenAI بلغة Python، يمكنك استخدام طريقة الرفع التقليديةmultipart/form-data مع تغيير model إلى gpt-image-2 فقط:
OPENAI_BASE_URL إلى https://api.xhuoapi.ai/v1/openai، وOPENAI_API_KEY إلى التوكن الذي حصلت عليه:
سلسلة نماذج Nano Banana
سلسلةnano-banana متاحة أيضاً عبر /openai/images/edits، فقط قم بتغيير model إلى أي نموذج في الجدول التالي:
| النموذج | التكلفة (رصيد / طلب) | السيناريو المناسب |
|---|---|---|
nano-banana | 0.14 | تعديل صور عادي، أسرع وأرخص |
nano-banana-2 | 0.28 | جودة وتفاصيل محسنة بشكل واضح |
nano-banana-pro | 0.35 | النموذج الرائد في السلسلة، أفضل احتفاظ بالهيكل، النص، والأسلوب |
مهم: نطاق دعم المعاملات 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)
آلية الاستدعاء غير المتزامنcallback_url متاحة أيضاً لنماذج nano-banana، وتتبع نفس عملية النماذج الأخرى، كما هو موضح في القسم التالي الاستدعاء غير المتزامن.
الاستخدام الأساسي
يمكنك الآن استخدام الكود لاستدعاء الواجهة، فيما يلي مثال باستخدام CURL:authorization، يمكن اختياره من القائمة المنسدلة. الثاني هو model، وهو اختيار نوع النموذج من موقع OpenAI الرسمي، لدينا نوع نموذج رئيسي واحد هنا، يمكن الاطلاع على التفاصيل في قائمة النماذج المتاحة. الثالث هو prompt، وهو النص الذي يصف الصورة المراد توليدها. والرابع هو image، وهو مسار الصورة التي نريد تعديلها، كما هو موضح في الصورة التالية:

OPENAI_BASE_URL إلى https://api.xhuoapi.ai/v1/openai، وOPENAI_API_KEY إلى التوكن الذي حصلت عليه من authorization. على نظام Mac OS يمكن تعيين المتغيرات عبر الأوامر:
gift-basket.png تم إنشاؤها في المجلد الحالي، والنتيجة كما يلي:

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. عند الانتهاء من التعديل، يتم إرسال نتيجة التعديل عبر طلب POST بصيغة JSON إلى عنوان callback_url المحدد، مع تضمين task_id لربط النتيجة بالمهمة.
فيما يلي مثال عملي.
أولاً، Webhook هو خدمة تستقبل طلبات HTTP، ويجب على المطور استبدالها بعنوان خادم HTTP الخاص به. لتسهيل العرض، نستخدم موقع Webhook عام https://webhook.site/، عند فتح الموقع تحصل على عنوان Webhook URL كما في الصورة:
انسخ هذا العنوان، مثلاً https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab، لاستخدامه كـ Webhook.
بعد ذلك، نحدد حقل callback_url بهذا العنوان مع باقي المعاملات، كما في الكود التالي:
task_id، وحقل data يحتوي على نفس نتائج تعديل الصورة كما في الاستدعاء المتزامن، مما يتيح ربط النتيجة بالمهمة عبر task_id.
معالجة الأخطاء
عند استدعاء API، إذا حدث خطأ، ستُرجع الواجهة رمز الخطأ والمعلومات ذات الصلة. مثلاً:400 token_mismatched: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.400 api_not_implemented: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة.401 invalid_token: غير مصرح، رمز التوثيق مفقود أو غير صالح.429 too_many_requests: عدد الطلبات كبير جداً، تجاوزت الحد المسموح.500 api_error: خطأ داخلي في الخادم.

