> ## 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. # طلب واستخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور > OpenAI generation 集成指南 - XHuoAPI خدمة تعديل الصور من OpenAI تتيح لك إرسال أي عدد من الصور والتعليمات، والحصول على الصور المعدلة. حالياً، تدعم الواجهة نماذج `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](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) والنقر على زر "Acquire" للحصول على بيانات الاعتماد اللازمة للطلب: ![](https://cdn.xhuoapi.ai/nyq0xz.png) إذا لم تكن مسجلاً أو مسجلاً دخولك، سيتم توجيهك تلقائياً إلى صفحة تسجيل الدخول لتسجيل حساب أو تسجيل الدخول، وبعد ذلك ستعود تلقائياً إلى الصفحة الحالية. عند التقديم لأول مرة، ستحصل على رصيد مجاني يمكن استخدامه مجاناً مع هذه الواجهة. ## نموذج 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`. تطبق نفس القيود الصارمة على الأحجام المخصصة: العرض والارتفاع يجب أن يكونا مضاعفات 16، والجانب الأطول ≤ 3840، وإجمالي عدد البكسلات ≤ 8,294,400. | النسبة | 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`:

نريد تحويلها إلى "الوضع الليلي" (Dark Mode). يمكن الاستدعاء كالتالي: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" }' ``` أو باستخدام Python: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` النتيجة المرجعة كالتالي: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.", "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` الصورة المعدلة كما يلي:

يمكن ملاحظة أن هيكل الوحدات، تقسيم المعلومات، وتنسيق الخطوط تم الاحتفاظ بها بدقة، وتم فقط عكس نظام الألوان إلى الوضع الداكن. > **ملاحظة**: حقل `image` يدعم أيضاً إرسال مصفوفة، مثلاً `"image": ["url1", "url2", "url3"]`، يمكن إرسال حتى 16 صورة مرجعية ليأخذ النموذج عدة صور في الاعتبار أثناء التعديل. ### طريقة الاستدعاء الثانية: JSON + عدة صور مرجعية يدعم `gpt-image-2` استخدام عدة صور مرجعية في نفس الوقت لإنشاء النتيجة النهائية، مثلاً دمج عدة صور منتجات في سلة هدايا واحدة: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.", "size": "1024x1024" } ``` ### مثال سيناريو: تغيير النمط مع الحفاظ على الهيكل مثال آخر، استبدال رف كتب خشبي بآخر عائم حديث، مع الحفاظ بدقة على عدد وترتيب الكتب في كل طبقة. الصورة الأصلية (رف كتب خشبي مولد بواسطة `gpt-image-2`):

الاستدعاء: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.", "size": "1024x1024" } ``` نتيجة التعديل (`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` فقط: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Convert this image to dark mode while keeping the layout intact." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` عند استخدام SDK، يجب تعيين متغيري بيئة: `OPENAI_BASE_URL` إلى `https://api.xhuoapi.ai/v1/openai`، و`OPENAI_API_KEY` إلى التوكن الذي حصلت عليه: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` ## سلسلة نماذج 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:;base64,...` قبل الإرسال)، أو يمكن إرسال رابط الصورة كسلسلة نصية في حقل النموذج. > * لا يدعم `mask`، `n`، `size`، `response_format` وغيرها؛ وسيتم تجاهلها إذا أرسلت. > * هيكل الرد يتبع تنسيق OpenAI (`data[].url`)، لكن `created` ثابت على `0`، ولا يعيد `b64_json`، و`revised_prompt` يساوي دائماً النص الأصلي `prompt`. ### استدعاء عبر نموذج + رابط صورة ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=add a green leaf on top of the apple" \ -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` النتيجة المرجعة: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "add a green leaf on top of the apple" } ] } ``` الصورة المعدلة:

### استدعاء عبر نموذج + ملف محلي ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "add a green leaf on top of the apple" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### الاستدعاء غير المتزامن (Callback) آلية الاستدعاء غير المتزامن `callback_url` متاحة أيضاً لنماذج nano-banana، وتتبع نفس عملية النماذج الأخرى، كما هو موضح في القسم التالي [الاستدعاء غير المتزامن](#异步回调). ## الاستخدام الأساسي يمكنك الآن استخدام الكود لاستدعاء الواجهة، فيما يلي مثال باستخدام CURL: ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Create a lovely gift basket with these this items in it' ``` عند استخدام هذه الواجهة للمرة الأولى، نحتاج إلى تعبئة أربعة عناصر على الأقل: الأول هو `authorization`، يمكن اختياره من القائمة المنسدلة. الثاني هو `model`، وهو اختيار نوع النموذج من موقع OpenAI الرسمي، لدينا نوع نموذج رئيسي واحد هنا، يمكن الاطلاع على التفاصيل في قائمة النماذج المتاحة. الثالث هو `prompt`، وهو النص الذي يصف الصورة المراد توليدها. والرابع هو `image`، وهو مسار الصورة التي نريد تعديلها، كما هو موضح في الصورة التالية:

كود Python المكافئ لاستدعاء الواجهة: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # حفظ الصورة في ملف with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` لاستخدام Python، يجب تعيين متغيري بيئة: `OPENAI_BASE_URL` إلى `https://api.xhuoapi.ai/v1/openai`، و`OPENAI_API_KEY` إلى التوكن الذي حصلت عليه من `authorization`. على نظام Mac OS يمكن تعيين المتغيرات عبر الأوامر: ```shell theme={null} export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai export OPENAI_API_KEY={token} ``` بعد الاستدعاء، ستجد صورة `gift-basket.png` تم إنشاؤها في المجلد الحالي، والنتيجة كما يلي:

بهذا نكون قد أكملنا عملية تعديل الصورة. حالياً، تدعم واجهة Edits ثلاثة نماذج: `dall-e-2`، `gpt-image-1`، و`gpt-image-2`، حيث يُنصح باستخدام `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/،](https://webhook.site/،) عند فتح الموقع تحصل على عنوان Webhook URL كما في الصورة: ![](https://cdn.xhuoapi.ai/cjjfly.png) انسخ هذا العنوان، مثلاً `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`، لاستخدامه كـ Webhook. بعد ذلك، نحدد حقل `callback_url` بهذا العنوان مع باقي المعاملات، كما في الكود التالي: ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Create a lovely gift basket with these items in it" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` بعد الاستدعاء، ستحصل فوراً على نتيجة مثل: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` بعد قليل، يمكنك مراقبة نتيجة تعديل الصورة على عنوان Webhook، وستكون المحتويات كما يلي: ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` يمكن ملاحظة وجود حقل `task_id`، وحقل `data` يحتوي على نفس نتائج تعديل الصورة كما في الاستدعاء المتزامن، مما يتيح ربط النتيجة بالمهمة عبر `task_id`. ## معالجة الأخطاء عند استدعاء API، إذا حدث خطأ، ستُرجع الواجهة رمز الخطأ والمعلومات ذات الصلة. مثلاً: * `400 token_mismatched`: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة. * `400 api_not_implemented`: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صحيحة. * `401 invalid_token`: غير مصرح، رمز التوثيق مفقود أو غير صالح. * `429 too_many_requests`: عدد الطلبات كبير جداً، تجاوزت الحد المسموح. * `500 api_error`: خطأ داخلي في الخادم. ### مثال على استجابة الخطأ ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## الخلاصة من خلال هذه الوثيقة، تعرفت على كيفية استخدام واجهة برمجة تطبيقات OpenAI Images Edits بسهولة للاستفادة من وظائف تعديل الصور الرسمية من OpenAI. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأفضل لهذه الواجهة. لأي استفسار، لا تتردد في التواصل مع فريق الدعم الفني لدينا.