> ## Documentation Index > Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # طلب واستخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور > OpenAI generation 集成指南 - Ace Data Cloud تقدم خدمة تعديل الصور من OpenAI إمكانية إدخال عدد غير محدود من الصور والتعليمات، وإخراج الصور المعدلة. تدعم الواجهة حاليًا نماذج `dall-e-2`، `gpt-image-1`، وأحدثها **`gpt-image-2`**، بالإضافة إلى نماذج سلسلة **`nano-banana` / `nano-banana-2` / `nano-banana-pro`** التي يتم الوصول إليها عبر نفس الواجهة. تشرح هذه الوثيقة بشكل رئيسي كيفية استخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور، والتي تمكننا من استخدام وظائف تعديل الصور الرسمية من OpenAI بسهولة. ## عملية الطلب لاستخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور، يمكنك أولاً زيارة صفحة [OpenAI Images Edits API](https://platform.acedata.cloud/documents/openai-images-edits) والنقر على زر "Acquire" للحصول على بيانات الاعتماد المطلوبة للطلب: ![](https://cdn.acedata.cloud/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` القيم `auto`، فارغة، أو بصيغة `WIDTHxHEIGHT` فقط، وأي شكل آخر يعيد خطأ 400. **يتم احتساب التكلفة لكل صورة موحدة بغض النظر عن دقة الصورة الأصلية أو قيمة `size` المطلوبة (1K / 2K / 4K / مخصصة).** تطبق القيود العليا على الأبعاد المخصصة أيضًا: العرض والارتفاع يجب أن يكونا من مضاعفات 16، والجانب الأطول ≤ 3840، وإجمالي عدد البكسلات ≤ 8,294,400. | النسبة | 1K موصى به | 2K موصى به | 4K موصى به | | ------ | ----------- | ----------- | ----------- | | 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 مع تطبيق التعديلات؛ وإذا كانت `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`:

نرغب في تحويلها إلى "الوضع الليلي". يمكننا الاتصال هكذا: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/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.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/openai`، و`OPENAI_API_KEY` إلى التوكن الذي حصلت عليه: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## نماذج سلسلة Nano Banana تدعم سلسلة `nano-banana` أيضًا التعديل عبر `/openai/images/edits`، فقط قم بتغيير `model` إلى أي نموذج من الجدول التالي: | النموذج | التكلفة (Credits / مرة) | سيناريو الاستخدام | | ----------------- | ----------------------- | ------------------------------------------------------------- | | `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.acedata.cloud/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.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` النتيجة المرجعة: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/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.acedata.cloud/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) يدعم نموذج nano-banana أيضًا آلية الاستدعاء غير المتزامن `callback_url`، وتتم العملية بنفس طريقة النماذج الأخرى، راجع القسم التالي [الاستدعاء غير المتزامن](#异步回调). ## الاستخدام الأساسي يمكنك الآن استخدام الكود لإجراء الطلب، فيما يلي مثال باستخدام 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.acedata.cloud/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.acedata.cloud/openai`، و`OPENAI_API_KEY` إلى التوكن الذي حصلت عليه من `authorization`. على نظام Mac OS يمكن تعيينهما بالأوامر التالية: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/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` يمثل معرف المهمة. عند الانتهاء من تعديل الصورة، يتم إرسال النتيجة إلى `callback_url` المحدد عبر POST بصيغة JSON، مع تضمين `task_id` لربط النتيجة بالمهمة. فيما يلي مثال عملي. أولًا، يجب أن يكون Webhook هو خدمة تستقبل طلبات HTTP، ويجب على المطور استبدالها بعنوان خادم HTTP الخاص به. للتجربة، يمكن استخدام موقع ويب Webhook عام مثل [https://webhook.site/،](https://webhook.site/،) حيث تحصل على عنوان Webhook كما في الصورة: ![](https://cdn.acedata.cloud/cjjfly.png) انسخ هذا العنوان، مثلاً `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`، واستخدمه كـ Webhook. بعدها، يمكن تعيين حقل `callback_url` إلى عنوان Webhook، مع ملء باقي الحقول كما في المثال التالي: ```shell theme={null} curl -X POST "https://api.acedata.cloud/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 URL، المحتوى كما يلي: ```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 لتعديل الصور بسهولة باستخدام وظائف تعديل الصور الرسمية من OpenAI. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسار، يرجى التواصل مع فريق الدعم الفني لدينا في أي وقت.