> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API 申请及使用 > OpenAI generation API guide - Ace Data Cloud OpenAI خدمة تعديل الصور، يمكن إدخال أي عدد من الصور والتعليمات، وإخراج الصور المعدلة. حاليًا، تدعم الواجهة كل من `dall-e-2`، `gpt-image-1`، وأحدث **`gpt-image-2`**، بالإضافة إلى نماذج سلسلة **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`** المتصلة من خلال نفس الواجهة. تتناول هذه الوثيقة بشكل رئيسي عملية استخدام OpenAI Images Edits API، مما يتيح لنا استخدام وظيفة تعديل الصور الرسمية من OpenAI بسهولة. ## 申请流程 لاستخدام OpenAI Images Edits API، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا. ![](https://cdn.acedata.cloud/5hmkdg.jpg) إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم العودة تلقائيًا إلى الصفحة الحالية. **رمز API واحد يكفي لاستدعاء جميع خدمات المنصة، ولا حاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ عند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin). > 📘 الوثيقة الكاملة: [OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## نموذج GPT-Image-2 `gpt-image-2` في سيناريو تعديل الصور يظهر تحسينات ملحوظة مقارنة بـ `gpt-image-1`: * **الهيكلية تبقى أكثر استقرارًا**: عند تغيير الجلد، أو الألوان، أو الخلفية، لن تتضرر تخطيط الصورة الأصلية تقريبًا. * **النصوص تحتفظ بدقة أكبر**: الصور التي تحتوي على نصوص مثل المعلومات الرسومية، الملصقات، القوائم، تظل النصوص واضحة وقابلة للقراءة بعد التعديل. * **يدعم نقل URL مباشرة**: بالإضافة إلى تحميل الملفات التقليدي `multipart/form-data`، `gpt-image-2` **يدعم أيضًا إدخال URL الصورة بطريقة JSON**، دون الحاجة لتحميل الصورة إلى الجهاز أولاً، مما يجعله مناسبًا تمامًا للتكامل مع خطوط الخدمة. * **يدعم نقل base64 مباشرة**: مثل الرسمي، يمكن أيضًا تمرير حقل `image` مباشرة كـ base64 (`data:image/png;base64,...` أو base64 عاري)، دون الحاجة لتحميل الصورة المحلية إلى موقع تخزين الصور قبل التعديل. * **يدعم إعادة رسم بدقة عالية**: يمكن إدخال صورة أصلية بدقة 1K، وطلب إخراج 2K / 4K من خلال معلمة `size`، سيقوم النموذج بإكمال التكبير أثناء عملية التعديل. ### تحويل رسمي / متغير عكسي (`:official` / `:reverse`) `gpt-image-2` يسير بشكل افتراضي على الخط العكسي. يمكن اختيار الخط بشكل صريح من خلال لاحقة اسم النموذج: * **`gpt-image-2:official`**: خط التحويل الرسمي. يدعم `n > 1` (إرجاع عدة صور في مرة واحدة) و 2K / 4K حقيقية، **يتم احتساب التكلفة لكل صورة، والسعر هو ضعف السعر الافتراضي لـ `gpt-image-2`**. حاليًا، متاح فقط من خلال قناة openai-hk، وعند عدم توفر الخط، سيتم إرجاع خطأ مباشرة، ولن يتم التراجع إلى الخط العكسي. * **`gpt-image-2:reverse`**: يعادل تمامًا `gpt-image-2` الافتراضي (الخط العكسي)، السعر يبقى كما هو. > القيود المتعلقة بمعلمة `n` المذكورة أدناه تنطبق فقط على الخط الافتراضي / العكسي؛ `gpt-image-2:official` يدعم `n > 1` ويتم احتساب التكلفة حسب الصورة. ### قيم `size` المدعومة تتطابق قيود واجهة التحرير على `size` تمامًا مع واجهة التوليد - `gpt-image-2` يحتاج فقط إلى أن تكون `size` إما `auto`، فارغ، أو يتوافق مع تنسيق `WIDTHxHEIGHT`، أي شكل آخر سيعيد 400. **جميع الأحجام (1K / 2K / 4K / مخصص) يتم خصمها بشكل موحد لكل صورة، ولا تتعلق بدقة الصورة الأصلية أو قيمة طلب `size`.** تطبق القيود الصارمة على الأحجام المخصصة أيضًا: يجب أن تكون الأبعاد مضاعفات 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؛ إذا تم تمرير `size` كـ `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-lite` / `nano-banana-2` / `nano-banana-pro`. `dall-e-2` هو النموذج الوحيد الذي يدعم حاليًا `n > 1` بشكل أصلي. فيما يلي مثالان حقيقيان من زوايا مختلفة لتجربة قدرة تعديل `gpt-image-2`. ### طريقة الاستدعاء الأولى: JSON + URL الصورة (موصى به) أرسل الطلب مباشرة بطريقة `application/json`، مع ملء حقل `image` بعنوان URL لصورة واحدة، سيقوم النموذج بجلب تلك الصورة وتعديلها وفقًا لـ `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": "قم بتحويل هذه المعلومات الرسومية إلى وضع الظلام: خلفية بحرية داكنة، نص كريمي فاتح، بطاقات وحدات رمادية داكنة مستديرة مع ظلال ناعمة. احتفظ بجميع التخطيطات والهياكل وترتيب الوحدات كما هي - فقط عكس نظام الألوان.", "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": "قم بتحويل هذه المعلومات الرسومية إلى وضع الظلام: خلفية بحرية داكنة، نص كريمي فاتح، بطاقات وحدات رمادية داكنة مستديرة مع ظلال ناعمة. احتفظ بجميع التخطيطات والهياكل وترتيب الوحدات كما هي - فقط عكس نظام الألوان.", "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": "قم بتحويل هذه المعلومات الرسومية إلى وضع الظلام: خلفية بحرية داكنة، نص كريمي فاتح، بطاقات وحدات رمادية داكنة مستديرة مع ظلال ناعمة. احتفظ بجميع التخطيطات والهياكل وترتيب الوحدات كما هي - فقط عكس نظام الألوان.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 编辑之后的图片如下：

可以看到模块结构、信息分区、字体排版都被严格保留，只有配色被反转为深色主题。 > **提示**：`image` 字段也支持传入一个数组，例如 `"image": ["url1", "url2", "url3"]`，最多可同时传入 16 张参考图，让模型综合参考多张图片进行编辑。 > **base64 直传**：`image`（及数组里的每一项）除了 URL，也可以是 base64 —— `data:image/png;base64,...` 或裸 base64 都行，适合本地图片不想先上传图床的场景。例如： > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "قم بتحويل هذه المعلومات الرسومية إلى وضع الظلام.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### 调用方式二：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": "اجمع جميع العناصر أعلاه في سلة هدايا واحدة 'استرخ واستمتع' على خلفية بيضاء نظيفة، واقعية، بإضاءة طبيعية ناعمة.", "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": "استبدل المكتبة الخشبية برف عائم حديث أبيض أنيق مثبت على جدار أزرق باهت. احتفظ بنفس ترتيب الكتب بالضبط (1 كتاب في الأعلى، 3 في المنتصف، 7 في الأسفل). أضف نبتة صغيرة في وعاء على الرف العلوي بجوار الكتاب. ضوء النهار الساطع من اليسار.", "size": "1024x1024" } ``` 编辑结果（`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`）：

可以看到风格和环境都按提示词进行了完整替换，但每层书本的数量（1 / 3 / 7）依旧严格保留，并且按要求增加了一盆多肉植物。 ### 调用方式三：multipart/form-data（兼容 OpenAI SDK） 如果你已经在使用官方 OpenAI Python SDK，原有的 `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="قم بتحويل هذه الصورة إلى وضع الظلام مع الحفاظ على التخطيط كما هو." ) 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` 设为申请到的 token： ```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-lite` | 0.14 | نموذج صور خفيف Gemini 3.1، يدعم فقط 1K، تحرير منخفض التأخير | | `nano-banana-2` | 0.28 | تحسين ملحوظ في الجودة والتفاصيل | | `nano-banana-pro` | 0.35 | الرائد في السلسلة، يحتفظ بأفضل هيكل ونص وأسلوب | > **مهم: نطاق دعم المعلمات** > يتصل Nano Banana عبر طبقة التكيف ببروتوكول OpenAI، ويدعم فقط المعلمات التالية: `model`، `prompt`، `image`. > > * يمكن رفع `image` إما عبر `multipart/form-data` (سيتم تحويله داخليًا إلى `data:;base64,...` وإرساله إلى المصدر)، أو يمكن تمرير سلسلة URL الصورة مباشرة عبر حقل النموذج. > * لا تدعم المعلمات `mask`، `n`، `size`، `response_format`، وما إلى ذلك؛ سيتم تجاهلها إذا تم ملؤها. > * يتبع هيكل الإرجاع تنسيق OpenAI (`data[].url`)، لكن `created` ثابت عند `0`، ولن يتم إرجاع `b64_json`، و`revised_prompt` دائمًا يساوي `prompt` الأصلي. ### استدعاء عبر النموذج + URL الصورة ```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_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.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`، حيث أن `model` هو نوع النموذج الذي نختار استخدامه من موقع OpenAI، هنا لدينا نموذج واحد رئيسي، يمكن الاطلاع على التفاصيل في النماذج المقدمة. المعلمة الأخرى هي `prompt`، حيث أن `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). ## ردود غير متزامنة نظرًا لأن وقت تحرير الصور عبر OpenAI Images Edits API قد يكون طويلًا نسبيًا، إذا لم يكن هناك استجابة من API لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للردود غير المتزامنة. تتضمن العملية العامة: عندما يقوم العميل بإرسال الطلب، يحدد حقل `callback_url` إضافي، بعد أن يقوم العميل بإرسال طلب API، ستقوم API على الفور بإرجاع نتيجة تحتوي على معلومات حقل `task_id`، تمثل معرف المهمة الحالية. عند اكتمال المهمة، سيتم إرسال نتيجة تحرير الصورة إلى `callback_url` المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل `task_id`، بحيث يمكن ربط نتيجة المهمة عبر المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، ردود Webhook هي خدمة يمكنها استقبال طلبات HTTP، يجب على المطورين استبدالها بعنوان URL الخاص بخادم HTTP الذي قاموا بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عام [https://webhook.site/،](https://webhook.site/،) افتح هذا الموقع للحصول على عنوان URL لـ Webhook، كما هو موضح في الصورة: ![](https://cdn.acedata.cloud/cjjfly.png) 将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`。 接下来，我们可以设置字段 `callback_url` 为上述 Webhook URL，同时填入相应的参数，如以下代码所示： ```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 时，如果遇到错误，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 API 轻松使用官方 OpenAI 的图像编辑功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。