واجهة برمجة تطبيقات تحرير الصور OpenAI: الأقنعة، والمعلمات، والأسعار، وسير العمل في GlobalGPT

تقوم واجهة برمجة التطبيقات OpenAI لتحرير الصور بتعديل صورة موجودة بناءً على موجه. المسار الأصلي هو POST /v1/images/edits; ؛ حيث يقبل الصورة، والموجه، وعناصر التحكم الاختيارية في التحرير مثل القناع أو الصور المرجعية. استخدم واجهة برمجة تطبيقات الصور (Image API) لتقديم طلب محدد، واستخدم واجهة برمجة تطبيقات الاستجابات (Responses API) عندما يحتاج المنتج إلى سير عمل متعدد المراحل للصور.

التحرير الموثوق به هو سلسلة عمليات بسيطة: تجميد الملف المصدر، وتحديد العناصر التي يجب أن تبقى، وتحديد العناصر التي يمكن تغييرها، وفحص البايتات التي يتم إرجاعها، وحفظ العنصر المعتمد. إذا كنت تفضل التنقل بين نماذج الصور وأدوات الوسائط الأخرى في مساحة عمل واحدة،, إنشاء الصور وتحريرها باستخدام GPT Image 2 in GlobalGPT; ؛ حيث تستخدم واجهة برمجة التطبيقات (API) العامة الخاصة بها عقد مهام غير متزامن مختلفًا، وهو ما يفصله هذا الدليل عن نقطة النهاية الأصلية لـ OpenAI.

جرب عدة نماذج للصورة العلوية على GlobalGPT

ما هي وظيفة واجهة برمجة تطبيقات تحرير الصور OpenAI؟

يبدأ مسار التعديل بصورة موجودة مسبقًا. تصف تعليماتك التغيير المطلوب، بينما توفر الصورة المدخلة السياق البصري الذي يجب الحفاظ عليه بعد التعديل. يمكنك استبدال الخلفية، أو إضافة عنصر أو إزالته، أو إجراء تعديل شامل على النمط، أو تمرير أكثر من صورة واحدة كمرجع. لا يزال النموذج يفسر الطلب؛ فالواجهة البرمجية (API) ليست محررًا للبكسلات مع حدود تحديد مضمونة.

يوثق OpenAI مسارين عمليين مفيدين. إن واجهة برمجة تطبيقات الصور هو الخيار المباشر عندما يتعين أن يُرجع طلب واحد صورة واحدة. إن واجهة برمجة تطبيقات الاستجابات يُعد الخيار الأفضل عندما يقوم المستخدم بمراجعة النتيجة، ويطلب إجراء تغيير آخر، ويحتفظ بسياق الصورة عبر الجولات المختلفة. ويؤثر هذا الاختيار على كل من شكل الطلب والرمز الذي يستخرج النتيجة.

قم بإجراء تعديل أولي باستخدام واجهة برمجة التطبيقات (API) الأصلية OpenAI

احتفظ بمفتاح واجهة برمجة التطبيقات (API) على الخادم الخاص بك وقم بتحميله من متغير بيئة. يرسل المثال أدناه صورة واحدة ومطالبة إلى نقطة نهاية التعديلات الموثقة. الـ صورة[] يمكن تكرار الحقل عندما يدعم النموذج المحدد مدخلات متعددة. يقوم مسار معالجة «shell» بفك تشفير أول صورة «base64» يتم إرجاعها وتحويلها إلى ملف PNG محلي.

curl -s \
  -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "image[]=@source.png" \
  -F "prompt=استبدل الخلفية فقط بمشهد استوديو باللون البيج الدافئ؛ مع الحفاظ على المنتج والملصق دون تغيير." \
| jq -r '.data[0].b64_json' \
| base64 --decode > edited.png

from openai import OpenAI
import base64

client = OpenAI()
result = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("source.png", "rb"),
    prompt="استبدل الخلفية فقط بمشهد استوديو باللون البيج الدافئ؛ مع الحفاظ على المنتج والملصق دون تغيير.",
)

image_bytes = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as output:
    output.write(image_bytes)

قبل أن تعتبر هذه النسخة جاهزة للإنتاج، تحقق من صحة الملف الذي تم فك تشفيره: تحقق من نوع MIME الخاص به، وأبعاده، وعدد البايتات، وما إذا كانت التفاصيل المرئية المهمة لا تزال موجودة. فالرد برمز 200 يشير فقط إلى أن الطلب قد قُبل؛ ولا يؤكد أن الملصق أو الشعار أو الشكل الهندسي للمنتج قد بقيت سليمة.

استخدم الأقنعة والصور المرجعية بطريقة آمنة

يُحدد القناع للنموذج المنطقة التي تريد تغييرها، لكن عملية إخفاء الصورة في GPT تظل تعتمد على المطالبة. ويحذر دليل نموذج OpenAI صراحةً من أن النموذج يستخدم القناع كدليل إرشادي وليس كحدود مطلقة للبكسلات. احرص على أن تكون المطالبة محددةً بشأن العنصر المراد حمايته، وقم بمراجعة الصورة بأكملها بعد إنشائها.

from PIL import Image

source = Image.open("source.png")
mask = Image.open("mask.png")

assert source.format == mask.format, (source.format, mask.format)
assert source.size == mask.size, (source.size, mask.size)
assert mask.width * mask.height > 0
assert mask.mode in {"RGBA", "LA"}, mask.mode
assert mask.fp is None or True  # تحقق من حجم الملف على القرص بشكل منفصل
print("source:", source.size, source.format)
print("القناع:", mask.size, mask.mode)

إذا قمت بتمرير عدة صور مع قناع، فإن الدليل الحالي ينص على أن القناع يُطبق على الصورة الأولى. ويُعد ذلك حدًا مفيدًا لتصميم سير عمل مرجعي: اجعل المدخل الأول هو العنصر الذي تنوي تعديل مساحته، وتعامل مع الصور المتبقية كمرجعيات بدلاً من افتراض أن القناع يشملها جميعًا.

تُحل الصور المرجعية مشكلة مختلفة. فهي يمكن أن توفر هوية المنتج، أو فئة الإضاءة، أو لوحة الألوان، أو تلميحًا بشأن التكوين. وهي لا تُجبر النموذج على الحفاظ على كل خط من خطوط الكفاف. وإذا كان لا بد من الحفاظ على شكل العبوة أو الملصق بالضبط دون تغيير، فاستخدم مرحلة مراجعة بصرية أو خطوة تحرير تقليدية بعد إنتاج النموذج.

اختر النموذج والمعلمات

تتضمن قائمة أدلة الصور الحالية لطراز OpenAI ما يلي: gpt-image-2.5-sunburst, gpt-image-2.5-flare, و gpt-image-2. تعامل مع أسماء النماذج والخيارات المدعومة على أنها وثائق قابلة للتغيير: تحقق من صفحة النموذج مباشرةً قبل دمجها، وقم بتثبيت نسخة مؤرخة إذا كانت قابلية التكرار أمرًا مهمًا.

ما هي تكلفة واجهة برمجة تطبيقات تحرير الصور OpenAI؟

تحدد OpenAI أسعار استخدام GPT Image وفقًا لفئات الرموز (tokens) بدلاً من سعر ثابت موحد لكل عملية تعديل. وتُدرج صفحة الأسعار الحالية أسعارًا منفصلة لكل من «إدخال الصور» و«الإدخال المخزّن مؤقتًا» و«إخراج الصور». لا تخضع عمليات التعديل المباشرة عبر واجهة برمجة تطبيقات الصور (Direct Image API) لمعاملة «المدخلات المخزنة مؤقتًا» الموثقة لأداة إنشاء الصور في واجهة برمجة تطبيقات الاستجابات (Responses API)، لذا لا تنسخ تقدير واجهة برمجة تطبيقات الاستجابات إلى واجهة برمجة تطبيقات الصور المباشرة /v1/الصور/التعديلات الميزانية.

*يتم عرض عمود «cached-input» في سياق التسعير المنشور. ويشير دليل التسعير إلى أن «cached-input» ينطبق على أداة إنشاء الصور في واجهة برمجة تطبيقات «Responses»، وليس على الطلبات المباشرة لواجهة برمجة تطبيقات «Images» مثل /v1/الصور/التعديلات. قد تتغير الأسعار؛ قم بالحساب بناءً على الاستخدام المحدد في طلبك.

def estimate_image_cost(image_input_tokens, image_output_tokens,
 input_rate, output_rate):
    return (image_input_tokens / 1_000_000) * input_rate + \
 (image_output_tokens / 1_000_000) * output_rate

# مثال فقط: استبدله بالاستخدام الموجود في ردك.
estimate = estimate_image_cost(
    image_input_tokens=250_000,
    image_output_tokens=120_000,
    input_rate=4.00,
    output_rate=15.00,
)
print(f"${estimate:.4f}")

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

يستخدم GlobalGPT عقد واجهة برمجة تطبيقات (API) مختلفًا لتحرير الصور

احصل على مفتاح API الآن

إن وثائق واجهة برمجة التطبيقات (API) لـ GlobalGPT يصف عملية إنشاء الصور ومقاطع الفيديو والتسجيلات الصوتية على أنها مهام وسائط غير متزامنة. وعنوان URL الأساسي العام له هو https://api2.glbgpt.com/ai-api/open/v1. أرسل ملف JSON إلى /المهام, ، استطلاع الرأي /tasks/{id}, ، واقرأ output.url بعد إنجاز مهمة بنجاح. يسرد كتالوج النماذج gpt-image-2 و gpt-image-2.5 كمسارات لتحرير الصور/المرجع تتضمن ما يصل إلى أربع صور مدخلة و نسبة العرض إلى الارتفاع.

وثائق واجهة برمجة التطبيقات العامة للموسم الخامس (S05): أدلة التوثيق العامة الخاصة بعقد المهام غير المتزامنة؛ ويفصل هذا المقال بينه وبين نقطة نهاية التعديلات متعددة الأجزاء الأصلية في OpenAI.

كتالوج النماذج العامة للموسم السادس: أدلة عامة من كتالوج النماذج تتعلق بمسارات GPT Image وحدود مهام الصور الموثقة الخاصة بها؛ يرجى التحقق من الاعتمادات والحقول الديناميكية قبل النشر.

BASE="https://api2.glbgpt.com/ai-api/open/v1"

# اختياري: إجراء تقدير دون إنشاء مهمة أو حجز رصيد.
curl "$BASE/tasks/estimate" \
  -H "Authorization: Bearer $GLOBALGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "حافظ على الزجاجة والملصق دون تغيير. استبدل الخلفية فقط بإضاءة استوديو بيج دافئة.",
    "images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
    "aspect_ratio": "3:2"
  }'

# لا ترسل إلا بعد التحقق من التقدير.
curl "$BASE/tasks" \
  -H "Authorization: Bearer $GLOBALGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-edit-example-001" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "احتفظ بالزجاجة والملصق دون تغيير. استبدل الخلفية فقط بإضاءة الاستوديو البيج الدافئة.",
    "images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
    "aspect_ratio": "3:2"
  }'

# استقصي معرّف المهمة المُرجع حتى يتم النجاح أو الفشل.
curl "$BASE/tasks/TASK_ID" \
  -H "Authorization: Bearer $GLOBALGPT_API_KEY"

لا تقم بلصق ملف OpenAI المكون من أجزاء متعددة قناع, دقة الإدخال, الحجم, أو الجودة الحقول في ملف JSON هذا ونفترض أنها تعمل. لا تذكر الوثائق العامة الحالية الخاصة بـ GlobalGPT هذه الحقول لمسار الصورة هذا. قد يتم حذف الحقول غير المدعومة وإعادة عرضها في المعلمات التي تم تجاهلها, ، لذا تحقق من هذا الرد قبل أن تستنتج أن الإعداد قد دخل حيز التنفيذ.

يقوم GlobalGPT بحجز الرصيد عند إرسال مهمة وسائط، ويقوم بتحريره عند فشل المهمة، ويبقي الوسائط الناجحة متاحة لمدة 30 يومًا وفقًا للوثائق العامة. احفظ الأصل الذي تم إرجاعه في مساحة تخزين تخضع لسيطرتك إذا كان من الضروري أن يظل الرابط صالحًا لفترة أطول. استخدم نقطة النهاية التقديرية قبل بدء الدفعة، ومفتاح التكرار عند إعادة محاولة طلب الشبكة، ومعرّف المهمة الأصلي عندما يكون الاستقصاء بطيئًا فحسب.

ما أظهره اختبار نموذج GlobalGPT

ولتوضيح هذا الفرق بشكل ملموس، أجريتُ اختبارًا محدودًا لواجهة برمجة تطبيقات (API) لنموذج GlobalGPT في 28 سبتمبر 2026 باستخدام موجهتي إدخال خياليتين لا تحملان علامة تجارية وموجهتي تعديل. استخدمت كل مهمة GPT Image 2، وطلب بنسبة 3:2، وأول ناتج صالح. الصور أدناه هي أدلة لاختبار النموذج، وليست جلسة عمل في متصفح، أو معيارًا قياسيًا، أو وعدًا بأن كل تعديل سيحافظ على كل خط محيطي.

مدخلات P00: الصورة الأصلية المجمدة: زجاجة خيالية لا تحمل علامة تجارية، مزودة بغطاء أبيض قصير وملصق قصير.

المرجع P01: الصورة المرجعية الثابتة: تُستخدم لأغراض الإضاءة واللون فقط، ولا تُعتبر هوية ثانية للمنتج.

T01: تعديل الخلفية لصورة واحدة

الطراز: صورة GPT 2 · التاريخ: 28 سبتمبر 2026 · الناتج: أول صورة صالحة بتنسيق PNG بدقة 1536×1024

عرض النص الكامل للمطالبة

حافظ على الزجاجة الخزفية، والغطاء الأبيض القصير، ونص الملصق الخيالي "NORTH" و"250ml"، والألوان، وزاوية التصوير، والنسب كما هي في الصورة الأصلية دون تغيير. استبدل فقط الخلفية البيضاء النقية ببيئة استوديو داخلية باللون البيج الدافئ مستوحاة من ضوء النافذة الناعم والظلال الخفيفة. لا تضف أي كائن جديد أو شعار أو كلمة أو علامة مائية أو شخص أو ملصق. اجعل الزجاجة هي العنصر الوحيد في التكوين الأفقي بنسبة 3:2.

ما يوضحه هذا: لا تزال الزجاجة واضحة، وملصق «NORTH / 250 مل» مرئي، ويتحول الخلفية البيضاء إلى مشهد داخلي باللون البيج الدافئ مع ظلال ناعمة تشبه ظلال النوافذ.

الحد الأقصى: هذا أحد النتائج الصحيحة الأولى. وهو لا يثبت الحفاظ الدقيق على البكسلات أو دقة التسميات بشكل عام.

T02: مرجع للإضاءة والألوان من صورتين

الطراز: صورة GPT 2 · التاريخ: 28 سبتمبر 2026 · الناتج: أول صورة صالحة بتنسيق PNG بدقة 1536×1024

عرض النص الكامل للمطالبة

استخدم الصورة المدخلة 1 كهوية دقيقة للمنتج، واستخدم الصورة المدخلة 2 فقط كمرجع للإضاءة البيج الدافئة ودرجة حرارة اللون والظلال الداخلية الناعمة. حافظ على شكل الزجاجة الخزفية، والغطاء الأبيض القصير، ونص الملصق الخيالي "NORTH" و"250ml"، والألوان، وزاوية التصوير، والنسب الموجودة في الصورة المدخلة 1 دون تغيير. استبدل الخلفية البيضاء بمشهد داخلي هادئ باللون البيج الدافئ في الاستوديو. لا تنسخ أي كائن إضافي أو نص أو شعار أو علامة مائية أو شخص أو ملصق من الصورة المدخلة 2. اجعل الزجاجة هي العنصر الوحيد في تركيبة أفقية بنسبة 3:2.

ما يوضحه هذا: يظل المنتج وملصق «NORTH / 250 مل» مميزين، بينما تتبنى المشهد الأجواء الدافئة باللون البيج التي تتميز بها الغرفة وسطح الطاولة وضوء النافذة في P01.

الحد الأقصى: لقد تغيرت بشكل واضح أبعاد غطاء الزجاجة، ومحيط الزجاجة، وموضعها. لا تصفوا ذلك بأنه الحفاظ على الهوية بشكل مثالي أو دقيق؛ بل استخدموا المقارنة اليدوية عندما يتعين أن تتطابق أبعاد البضائع.

كيفية استخدام هذه الأدلة: والنتيجة المفيدة هي إنشاء بوابة مراجعة قابلة للتكرار. قم بتثبيت عنوان URL المدخل، وتسمية الموضوع المحمي، ووصف الدور المرجعي، وفحص البايتات المُرجعة، ومقارنة المنتج المعتمد بالمصدر قبل النشر. يمكن أن ينجح نقل الأسلوب حتى مع استمرار انحراف الشكل الهندسي.

التعامل مع الأخطاء والاستجابات البطيئة

افصل أدلة النقل عن أدلة الجودة. فحد الوقت الأقصى، أو فشل DNS، أو استجابة سعة المزود تعني أنه ليس لديك صورة صالحة للتقييم. وعلى العكس من ذلك، فإن الصورة الصالحة التي تم تغيير غطاءها أو تسميتها تُعد نتيجة بصرية يجب الإبلاغ عنها كما هي، حتى لو كان التكوين يبدو جذابًا.

قائمة مراجعة لتحرير الصور تتوافق مع معايير الإنتاج

1. تجميد المصدر: تخزين ملف الإدخال، والأبعاد، والتنسيق، والقيمة التجزئية.
2. تعيين أدوار الصور: تحديد الصورة المعنية وأي مراجع تتعلق بالإضاءة أو الألوان أو التكوين.
3. إشارات محمية ضد الكتابة: اذكر العلامة التجارية، والقصّة، والألوان، والنسب التي تحتاج إلى مراجعة.
4. اختر العقد: استخدم النمط متعدد الأجزاء OpenAI لنقطة نهاية التعديلات الأصلية، أو مهام JSON GlobalGPT لواجهة برمجة تطبيقات الوسائط العامة الخاصة بها.
5. تقدير التكاليف وتقديمها: استخدم أسعار OpenAI الحالية أو GlobalGPT /المهام/التقدير; ؛ إضافة مفتاح إيدمبوتنسي لضمان أمان عمليات الإرسال عند إعادة المحاولة.
6. الاستقصاء وفك الترميز: الاحتفاظ بمعرّف المهمة الواحد، والتحقق من صحة الملف المُرجع، وحفظ البايتات أو عنوان URL في مساحة التخزين المعتمدة.
7. الموافقة بصريًّا: قارن الناتج مع النص الأصلي قبل إدراجه في كتالوج المنتجات أو الإعلان أو الصفحة الموجهة للعملاء.

إذا كنت ترغب في تنفيذ نفس العملية دون الحاجة إلى دمج لوحات معلومات النماذج المنفصلة، فجرب صورة GPT 2 في GlobalGPT. للاطلاع على النسخة المخصصة للمتصفح من مسار العمل، انظر تحرير الصور في مساحة العمل GlobalGPT; ؛ للاطلاع على مناقشة أوسع نطاقًا حول الإعدادات والأسعار، انظر إعداد واجهة برمجة تطبيقات GPT Image وأسعارها.

الأسئلة الشائعة

ما هي واجهة برمجة تطبيقات تحرير الصور OpenAI؟

إنها مسار تحرير الصور على POST /v1/images/edits. تقوم بإرسال صورة مدخلة وموجهة، مع إمكانية إضافة قناع أو صور مرجعية بشكل اختياري، ثم تقوم بفك تشفير بيانات الصورة التي يتم إرجاعها. استخدم واجهة برمجة تطبيقات الصور (Image API) لإجراء تعديل واحد، واستخدم واجهة برمجة تطبيقات الردود (Responses API) عندما يحتاج المنتج إلى محادثة متعددة الجولات حول الصورة.

هل تُرجع واجهة برمجة تطبيقات تحرير الصور OpenAI رابطًا عامًا للصورة؟

تُرجع الأمثلة الموثقة لواجهة برمجة تطبيقات الصور (Image API) بيانات بتنسيق b64_json. قم بفك تشفير تلك البايتات، وتحقق من صحة الملف، واحفظه في مساحة تخزين تديرها أنت. لا تفترض أن الاستجابة الناجحة هي عنوان URL لشبكة توزيع المحتوى (CDN) مستضافة.

هل قناع الصورة OpenAI يمثل اختيارًا دقيقًا للبكسلات؟

لا. تعمل القناع على توجيه عملية التحرير بناءً على المطالبات. يمكن للنموذج تغيير البكسلات المحيطة بالمنطقة المطلوبة، لذا يجب التحقق من التسميات وتفاصيل المنتج وعلامات السلامة والعناصر الأخرى التي يجب أن تظل صحيحة.

كم عدد الصور المدخلة التي يمكن أن يستخدمها برنامج تحرير الصور؟

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

هل يمكنني إرسال طلب OpenAI /v1/images/edits إلى GlobalGPT عن طريق تغيير قيمة base_url؟

يستخدم عقد الوسائط العامة لـ GlobalGPT طلب JSON POST إلى /tasks، ثم طلب GET إلى /tasks/{id}، مع تضمين الصور ونسبة العرض إلى الارتفاع (aspect_ratio) حيثما يقبلها النموذج المحدد. لا تذكر الوثائق العامة قناع multipart الخاص بـ OpenAI، ولا عقد input_fidelity أو size أو quality لهذا المسار.

كيف يمكنني تقدير صعوبة مهمة معالجة الصور قبل إرسالها؟

بالنسبة لـ GlobalGPT، أرسل نص JSON نفسه إلى /tasks/estimate أولاً. فهذا لا يؤدي إلى إنشاء مهمة أو حجز أرصدة. أما بالنسبة لـ OpenAI، فاحسب التكلفة باستخدام الأسعار الحالية لكل مليون توكن، ثم تحقق من الاستخدام الفعلي في الرد أو سجل الفوترة.