طلب واستخدام واجهة برمجة تطبيقات 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 والنقر على زر “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.

النسبة	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:

نرغب في تحويلها إلى “الوضع الليلي”. يمكننا الاتصال هكذا:

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:

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)

النتيجة المرجعة:

{
  "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 استخدام عدة صور مرجعية لإنشاء النتيجة النهائية، مثل دمج عدة صور منتجات في سلة هدايا واحدة:

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):

الطلب:

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:

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 إلى التوكن الذي حصلت عليه:

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:<mime>;base64,... وإرساله للأعلى)، أو تمرير رابط الصورة مباشرة كسلسلة نصية في حقل النموذج.
• لا تدعم المعاملات mask، n، size، response_format؛ سيتم تجاهلها إذا تم تمريرها.
• تتبع النتيجة تنسيق OpenAI (data[].url)، لكن created ثابت على 0، ولا يتم إرجاع b64_json، وrevised_prompt يساوي دائمًا prompt الأصلي.

​

الاتصال عبر نموذج + رابط صورة

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"

النتيجة المرجعة:

{
  "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"
    }
  ]
}

الصورة المعدلة:

​

الاتصال عبر نموذج + ملف محلي

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 -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 المكافئ لنفس الطلب:

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 يمكن تعيينهما بالأوامر التالية:

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.

​

الاستدعاء غير المتزامن (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، مع ملء باقي الحقول كما في المثال التالي:

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"

بعد الطلب، ستتلقى فورًا نتيجة مثل:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

بعد فترة قصيرة، يمكنك مشاهدة نتيجة تعديل الصورة على Webhook URL، المحتوى كما يلي:

{
  "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: خطأ داخلي في الخادم، حدث خطأ ما في الخادم.

​

مثال على استجابة خطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

الخلاصة

من خلال هذه الوثيقة، تعرفت على كيفية استخدام واجهة برمجة تطبيقات OpenAI لتعديل الصور بسهولة باستخدام وظائف تعديل الصور الرسمية من OpenAI. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسار، يرجى التواصل مع فريق الدعم الفني لدينا في أي وقت.