الانتقال إلى المحتوى الرئيسي

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 تتيح لك إرسال أي عدد من الصور والتعليمات، والحصول على الصور المعدلة. حالياً، تدعم الواجهة نماذج 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.
تطبق نفس القيود الصارمة على الأحجام المخصصة: العرض والارتفاع يجب أن يكونا مضاعفات 16، والجانب الأطول ≤ 3840، وإجمالي عدد البكسلات ≤ 8,294,400.
النسبة1K (السعر القياسي)2K موصى به (×1.5)4K موصى به (×1.5)
1:11024x10242048x20482880x2880
4:31536x10242048x15363264x2448
3:41024x15361536x20482448x3264
16:91792x10242048x11523840x2160
9:161024x17921152x20482160x3840
على سبيل المثال: إذا كانت الصورة الأصلية 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). يمكن الاستدعاء كالتالي:
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:
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)
النتيجة المرجعة كالتالي:
{
  "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 استخدام عدة صور مرجعية في نفس الوقت لإنشاء النتيجة النهائية، مثلاً دمج عدة صور منتجات في سلة هدايا واحدة:
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.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 فقط:
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 إلى التوكن الذي حصلت عليه:
export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token}

سلسلة نماذج Nano Banana

سلسلة nano-banana متاحة أيضاً عبر /openai/images/edits، فقط قم بتغيير model إلى أي نموذج في الجدول التالي:
النموذجالتكلفة (رصيد / طلب)السيناريو المناسب
nano-banana0.14تعديل صور عادي، أسرع وأرخص
nano-banana-20.28جودة وتفاصيل محسنة بشكل واضح
nano-banana-pro0.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.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"
النتيجة المرجعة:
{
  "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"
    }
  ]
}
الصورة المعدلة:

استدعاء عبر نموذج + ملف محلي

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 -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[][email protected]" \
  -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.xhuoapi.ai/v1/openai، وOPENAI_API_KEY إلى التوكن الذي حصلت عليه من authorization. على نظام Mac OS يمكن تعيين المتغيرات عبر الأوامر:
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.

الاستدعاء غير المتزامن (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 بهذا العنوان مع باقي المعاملات، كما في الكود التالي:
curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -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، وستكون المحتويات كما يلي:
{
  "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 Images Edits بسهولة للاستفادة من وظائف تعديل الصور الرسمية من OpenAI. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأفضل لهذه الواجهة. لأي استفسار، لا تتردد في التواصل مع فريق الدعم الفني لدينا.