OpenAI Images Edits API 申请及使用

​

申请流程

📘 الوثيقة الكاملة: OpenAI Images Edits API →

​

GPT-Image-2 模型

• الحفاظ على الهيكل أكثر استقرارًا: عند تغيير الجلد، تغيير الألوان، أو تغيير الخلفية، لن يتم تدمير تنسيق الصورة الأصلية وتكوينها تقريبًا.
• احتفاظ النص بدقة أكبر: الصور التي تحتوي على نصوص مثل المعلومات الرسومية، الملصقات، القوائم، وغيرها، تظل النصوص واضحة وقابلة للقراءة بعد التحرير.
• دعم نقل URL مباشرة: بالإضافة إلى تحميل الملفات التقليدي multipart/form-data، gpt-image-2 يدعم أيضًا إدخال URL الصورة بطريقة JSON، دون الحاجة إلى تنزيل الصورة محليًا أولاً، مما يجعله مناسبًا جدًا للاتصال بخطوط الخدمة.
• دعم نقل base64 مباشرة: كما هو متفق عليه رسميًا، يمكن أيضًا تمرير حقل image مباشرة كـ base64 (data:image/png;base64,... أو base64 عاري)، دون الحاجة إلى تحميل الصورة المحلية إلى موقع تخزين الصور أولاً لتحريرها.
• دعم إعادة رسم بدقة عالية: يمكن إدخال صورة أصلية بدقة 1K، من خلال معلمة size طلب إخراج بدقة 2K / 4K، سيقوم النموذج بإكمال التكبير أثناء عملية التحرير.

​

线路变体（:official / :reverse）

• gpt-image-2:official: قناة رسمية، مستقرة ومتوافقة. يتم تحديد التكلفة من خلال رموز إدخال النص، ورموز إدخال الصورة أثناء التحرير ورموز إخراج الصورة، ويتم التسوية النهائية وفقًا للاستخدام الفعلي في الاستجابة؛ الأسعار المعروضة للجودة/الحجم على الصفحة هي للتقدير فقط؛ يتم احتساب الأسعار للعملاء بحوالي 80% من السعر الرسمي لـ OpenAI وفقًا لأقصى حزمة استخدام. ستقوم الخدمة تلقائيًا بتجاوز الأخطاء بين القنوات المتاحة، والقدرة والتكلفة تعتمد على النتائج الفعلية المستلمة.
• gpt-image-2:reverse: يعادل تمامًا gpt-image-2 الافتراضي، مع قيمة أفضل، والسعر يبقى كما هو.

:official 计费公式 التكلفة النهائية = رموز إدخال النص + رموز إدخال الصورة (فقط للتحرير) + رموز إخراج الصورة. السعر المعروض على الصفحة لـ quality × size هو تقدير قبل الطلب، ويتم خصم التكلفة الفعلية وفقًا لـ usage في الاستجابة الناجحة. على سبيل المثال، عادةً ما تكون تكلفة إخراج الصورة لـ low، 1024x1024 حوالي 0.0505 Credits، بالإضافة إلى عدد قليل من رموز الإدخال؛ عند استخدام auto، قد يختار النموذج جودة أعلى، وسيتم فحص الحد المسبق وفقًا لمستوى أعلى.

​

支持的 size 取值

على سبيل المثال: إذا كانت الصورة الأصلية 1024x1024، وعند تمرير size كـ 2048x2048، سيقوم النموذج بإعادة رسم الصورة وإخراج صورة بدقة 2K؛ إذا تم تمرير size كـ 3840x2160، سيتم إخراج صورة بدقة 4K. يتم خصم تكاليف الأبعاد الثلاثة لـ gpt-image-2 الافتراضي و:reverse بشكل متساوٍ؛ بينما يتم احتساب :official وفقًا للاستخدام الفعلي للرموز. إغفال حقل size وتمريره كـ auto متساوي تمامًا: سيقوم gpt-image-2 بقراءة نية الحجم المحددة في الكلمات الدلالية، بما في ذلك البكسلات، النسبة، الاتجاه الأفقي أو العمودي، مستوى الدقة (مثل 4K / high-res) أو اسم القماش. عند التعرف على نية الحجم، سيتم استخدام الأبعاد المحددة المخططة؛ إذا لم يكن هناك متطلبات حجم في الكلمات الدلالية أو لم يكن من الممكن الحكم تلقائيًا، سيتم الرجوع إلى حجم الصورة المرجعية الأولى. سيتم تطبيع الأبعاد النهائية المحددة قبل تقديم الطلب إلى مضاعفات 16، مع قيود على الطول وإجمالي عدد البكسلات؛ إذا كنت بحاجة إلى تحكم مطلق، يرجى تمرير WIDTHxHEIGHT مباشرة. بعد الانتهاء من التوليد، لن يتم إعادة المحاولة تلقائيًا بسبب اختلاف بكسلات الإخراج، لتجنب تكاليف التوليد المكررة. حول معلمة n تدعم واجهة تحرير gpt-image-2 n > 1: يمكن أن تعيد طلب واحد العدد المقابل من نتائج التحرير. بشكل افتراضي، يتم احتساب gpt-image-2 و :reverse بناءً على عدد الصور الناجحة؛ بينما يتم احتساب :official بناءً على الاستخدام الفعلي للتوكن في الاستجابة الكاملة (تتراوح قيم n من 1 إلى 10). ينطبق نفس الشيء على gpt-image-1 / gpt-image-1.5، وكذلك سلسلة nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. لاحظ أن response_format=b64_json يدعم فقط n=1، وعند استخدام n>1 يرجى استخدام الإرجاع الافتراضي عبر URL. إذا فشلت بعض الصور في التوليد، فسيتم إرجاع واحتساب الجزء الناجح فقط.

​

طريقة الاستدعاء الأولى: JSON + URL الصورة (موصى بها)

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"
  }'

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 صورة مرجعية في وقت واحد، مما يسمح للنموذج بالرجوع إلى عدة صور لإجراء التحرير.

إرسال base64 مباشرة: يمكن أن يكون image (وكل عنصر في المصفوفة) أيضًا base64 — data:image/png;base64,... أو base64 عاري، مناسب للصور المحلية التي لا ترغب في تحميلها على موقع رفع الصور أولاً. على سبيل المثال:

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": "Convert this infographic to dark mode.",
    "size": "1024x1536"
}
requests.post("https://api.acedata.cloud/openai/images/edits", json=payload,
              headers={"authorization": "Bearer {token}"})

​

طريقة الاستدعاء الثانية: JSON + عدة صور مرجعية

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

​

مثال على السيناريو: تغيير النمط + الحفاظ على الهيكل

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

​

طريقة الاستدعاء الثالثة: multipart/form-data (متوافقة مع OpenAI SDK)

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)

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

​

نماذج Nano Banana

مهم: نطاق دعم المعلمات تتصل Nano Banana ببروتوكول OpenAI من خلال طبقة التكيف، وتدعم فقط المعلمات التالية: model، prompt، image، n.

• يمكن تحميل image إما عبر multipart/form-data (سيتم تحويل الملفات المحلية تلقائيًا إلى base64)، أو يمكن تمرير سلسلة URL الصورة مباشرة عبر حقل النموذج.
• لا تدعم المعلمات مثل mask، size، response_format؛ إذا تم ملؤها، سيتم تجاهلها. n > 1 مدعوم (1–10)، وسيتم إرجاع عدد نتائج التحرير المقابلة مع احتساب التكلفة.
• تتبع بنية الإرجاع تنسيق OpenAI (data[].url)، لكن created ثابت عند 0، ولن يتم إرجاع b64_json، و revised_prompt دائمًا يساوي prompt الأصلي.

​

استدعاء عبر النموذج + URL الصورة

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=أضف ورقة خضراء فوق التفاحة" \
  -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": "أضف ورقة خضراء فوق التفاحة"
    }
  ]
}

​

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

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": "أضف ورقة خضراء فوق التفاحة"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

​

ردود غير متزامنة

​

الاستخدام الأساسي

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=أنشئ سلة هدايا جميلة مع هذه العناصر فيها'

تلميح: يمكن أن تظهر image[] عدة مرات لتحميل صور مرجعية متعددة، مثل -F "image[]=@a.png" -F "image[]=@b.png"، تدعم نماذج GPT Image ما يصل إلى 16 صورة (كل صورة لا تتجاوز 50 ميجابايت، بصيغة png/webp/jpg). إذا تجاوزت العدد، ستعود 400.

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
قم بإنشاء صورة فوتوغرافية واقعية لسلة هدايا على خلفية بيضاء 
موسومة بـ 'استرخ واستمتع' مع شريط وخط يشبه الكتابة اليدوية، 
تحتوي على جميع العناصر في الصور المرجعية.
"""

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)

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

​

异步回调

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

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

​

错误处理

• 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"
}

​

结论