ملاحظة الكاتب: المطورون الذين يستخدمون بالفعل image_generation من Responses في APIYI من أجل “توليد الصور أثناء الدردشة”، يمكنهم بعد الانتقال إلى Images API المستقل أن يحافظوا على التعديل المتتالي للصور باتباع الطريقة الموضحة في هذا المقال.
الخلاصة قبل كل شيء: اهجر فقط الجزء الخاص بتوليد الصور، ولا تمس المحادثة النصية الأصلية. ما كان يُربط ضمنيًا عبر previous_response_id باسم “الصورة السابقة” أصبح الآن مسؤولية تطبيقك: هو الذي يحفظها، ويختارها صراحةً عند كل عملية تعديل، ويرفعها كصورة أصلية إلى POST /v1/images/edits. وبعد ذلك تبقى نتائج التعديل على مدى عدة جولات كما هي دون تغيير، والفرق الوحيد هو من يتذكّر “الصورة السابقة”.
هذه الخلاصة صحيحة بشرط تحديث المستندات الذي نشره APIYI في 2026-11-21 الساعة 22:30 (بتوقيت بكين). فقد تغيّر توصية استخدام خمسة نماذج صور محوّلة رسميًا لتصبح عبر نقطتي نهاية مستقلتين للصور. ولم توقف OpenAI خدمة Responses، والمحادثات النصية داخل الموقع تعمل كالمعتاد. جميع الواجهات والحقول وقواعد الفوترة الواردة أدناه مأخوذة من مستندات APIYI على apiyi.com ومن دليل توليد الصور الرسمي من OpenAI. والشيفرة هنا أمثلة توثيقية ولا تمثل نتائج اختبار فعلي.

خريطة معارف وفهرس ترحيل GPT Image API
يتم الترحيل بالكامل على أربع خطوات، ومخرجات كل خطوة هي مدخلات الخطوة التالية:
تحديد الاستدعاءات القديمة وتقسيم المسارات (القسم 1)
└─> المخرجات: ما إذا كان كل طلب يجب أن يمر عبر المحادثة أو generations أو edits
توليد الصورة الأولى وحفظها (القسم 2.1)
└─> المخرجات: ملف v1.png بعد التحقق منه + سجل الأصل
تسليم الصورة الأصلية المختارة إلى واجهة التحرير (القسم 2.2)
└─> المخرجات: v2.png + ربط parent_asset_id
الاستلام والمطابقة المحاسبية (القسم 3)
└─> المخرجات: قائمة الصور الصالحة + تكلفة كل صورة مقبولة

| الخطوة | ما تعتمد عليه | لماذا هي في هذا الترتيب | الهدف |
|---|---|---|---|
| 1 تقسيم المسارات | قائمة الاستدعاءات الموجودة في الكود الحالي | تحديد موضع التعديل أولاً حتى لا نغيّر المحادثات النصية بالخطأ | تحويل طلبات توليد الصور فقط إلى Images API |
| 2.1 أول توليد للصورة | مسار generations الذي حُدد في الخطوة 1 | التعديلات اللاحقة تحتاج إلى صورة أصلية محفوظة فعليًا | الحصول على v1 بعد التحقق منه وتسجيله في المخزون |
| 2.2 متابعة تعديل الصورة | ملف v1 المحفوظ في الخطوة 2.1 | النقطة المستقلة لا تعترف بـ previous_response_id، بل تعترف فقط بالصورة التي ترفعها أنت |
الحصول على v2 مع تدوين علاقة الأب بالابن |
| 3 الاستلام والمطابقة المحاسبية | صور الخطوة 2 وسجلات الكونسول | الصور التي تجتاز الاستلام فقط هي التي تُحتسب في مقام التكلفة | صور قابلة للتسليم + فاتورة قابلة للتفسير |
اقتراح ترتيب القراءة: القسم 1 إلزامي؛ والقسم 2 اتبعه وفق ترتيب الكود خطوة بخطوة؛ أما القسم 3 فراجعه قبل الإطلاق أو عند حدوث انقطاع في الاتصال أو وجود تساؤلات حول الفاتورة.
للعلم: مصطلحات ترحيل GPT Image API
| المصطلح | شرح موجز |
|---|---|
| التمرير الرسمي | نموذج قناة التمرير الرسمي الذي توفره APIYI، ويُقصد به في هذا المقال معرفات خمسة نماذج صور |
| image_generation | أداة توليد الصور داخل Responses API، والمسار القديم يمر عبرها ليولّد الصور أثناء المحادثة |
| previous_response_id | معامل يستخدمه Responses لاستمرار سياق الجولة السابقة، وطلبات Images المستقلة لا تستقبله |
| multipart | صيغة رفع النماذج، ويستخدمها /images/edits لرفع بايتات الصورة الحقيقية |
| b64_json | الحقل الذي تعيده نقطة الصور المستقلة، ومحتواه صورة بترميز base64 |
| parent_asset_id | حقل ربط يسجله التطبيق بنفسه لبيان «من أي صورة جاءت هذه الصورة» |
1 ما استدعاءات GPT Image API التي يجب ترحيلها بعيدًا عن Responses؟
1.1 نطاق تحديث GPT Image API بتاريخ 11/21 والنماذج الخمسة الرسمية المحوّلة
يشمل تحديث الوثائق هذا معرّفات النماذج الخمسة الرسمية المحوّلة التالية:
gpt-image-2.6-sunburstgpt-image-2.6-flaregpt-image-2.5-sunburstgpt-image-2.5-flaregpt-image-2
نقاط النهاية المستقلة للصور المقابلة هي POST /v1/images/generations (محتوى طلب JSON) وPOST /v1/images/edits (نموذج multipart). لا توصي APIYI بمواصلة استخدام مسار image_generation في Responses لتوليد الصور، وذلك لسببين: عدم استقرار التوريد، وتحمّل رسوم أدوات إضافية. كما أن Chat Completions لا يدعم توليد الصور باستخدام نماذج الصور الرسمية المحوّلة الخمسة هذه، وإذا كانت الشيفرة القديمة تستخدم هذا الأسلوب فيجب إدراجه أيضًا في قائمة الترحيل.
تجدر الإشارة إلى أن هذا التعديل لا يؤثر إلا على توليد الصور. لم توقف OpenAI خدمة Responses، كما لم يتم إيقاف المحادثات النصية داخل APIYI. لذلك يقتصر نطاق الترحيل على الجزء من الشيفرة الذي «يستدعي أداة صور أو نموذج صور» داخل الطلب. أما كيفية الاختيار بين النماذج الخمسة فهي موضوع آخر، ويمكن الرجوع إلى مقال اختيار النموذج في مركز المساعدة الخاص بـ APIYI على apiyi.com؛ ولن نتعمق فيه هنا.
1.2 مسارات GPT Image API: المحادثة النصية، والتوليد الأول للصورة، ومتابعة التعديل
الطريقة التي يقترحها قسم الأسئلة الشائعة (FAQ) في APIYI هي: يتولى نموذج المحادثة تحديد نية المستخدم، ثم يستدعي التطبيق واجهة Images API بشكل منفصل ويدير الصور بنفسه. وبناءً على هذا المنطق، يمكن تفكيك المهام الثلاث التي كان طلب Responses الواحد يتولاها جميعًا إلى ثلاثة مسارات:
| نية المستخدم | المسار الجديد | صيغة الطلب | مصدر الصورة |
|---|---|---|---|
| محادثة نصية خالصة، وسؤال وجواب | الاحتفاظ بواجهة المحادثة النصية الأصلية | دون تغيير | لا يوجد |
| التوليد الأول للصورة | POST /v1/images/generations |
JSON | الموجه فقط (prompt) |
| متابعة التعديل على صورة معينة | POST /v1/images/edits |
multipart | التطبيق يرفع الصورة الأصلية المحددة |
في Responses الأصلي، يمكن تحقيق استمرارية التعديل عبر previous_response_id، أو عبر تمرير الصورة مباشرة. أما طلبات Images المستقلة فلا تقبل previous_response_id، وهذا هو السبب الجذري وراء اضطرار التطبيق إلى تولي مسؤولية «التعديل على مدى جولات متعددة». فلم يعد النموذج يتذكر لك الصورة السابقة، وعليك أنت أن تسلّمه ملف تلك الصورة.
إذا قال المستخدم «زدها احمرارًا قليلًا»، لكن المحادثة تحتوي بالفعل على عدة نسخ v1 وv2 وv3، فلن يستطيع التطبيق تحديد أي نسخة يقصد، وفي هذه الحالة ينبغي التأكد من المستخدم أولًا بدلًا من التخمين. قد يبدو الاعتماد افتراضيًا على أحدث نسخة أمرًا مريحًا، لكن إذا كان المستخدم في الواقع يريد العودة إلى v2 ليعيد التعديل عليها، فسيُحسب عليه رسم إضافي بلا داعٍ، وسيزداد الأمر ارتباكًا بالنسبة له.
يجب أن يتغير تحليل الاستجابة هو الآخر:

| المسار | موقع الصورة في الاستجابة | طريقة استمرارية السياق |
|---|---|---|
| Responses + image_generation | حقل result في العنصر الذي يحمل type=image_generation_call داخل output |
previous_response_id أو تمرير الصورة |
| Images API المستقلة | data[0].b64_json |
التطبيق يرفع الصورة الأصلية المحددة |
2 كيفية تعديل الصورة السابقة عبر GPT Image API
يشرح المثال التالي، الذي يتكون من جولتين، سير العمل الكامل. في الجولة الأولى نولّد كوبًا أزرق، وفي الجولة الثانية نغيّر لون جسم الكوب فقط إلى الأحمر الطوبي. نستخدم المعطيات نفسها الواردة في مثال توثيق APIYI: النموذج gpt-image-2.5-sunburst، والمقاس 1024x1024، وquality=medium، وoutput_format=png. يُقرأ الرمز المميز من متغير البيئة APIYI_KEY ويُمرر بأسلوب Bearer.
2.1 توليد كوب أزرق بصيغة PNG عبر GPT Image API والتحقق منه
في الجولة الأولى نستدعي نقطة النهاية generations، ويصف الموجه: خلفية رمادية فاتحة، كوب خزفي أزرق في المنتصف، المقبض باتجاه اليمين، إضاءة جانبية ناعمة، ولا يوجد نص في الصورة. بعد استلام الاستجابة ننفذ الخطوات التالية بالترتيب:
- نستدعي
raise_for_status()أولًا لاستبعاد أي فشل على مستوى HTTP. - نفكّ ترميز
b64_jsonفكًا صارمًا وفق base64، وإذا تعذر فك الترميز نعتبر العملية فاشلة. - نفتح الملف باستخدام Pillow ونستدعي
load()للتأكد من أن الملف يمكن فك ترميزه إلى صورة فعلًا. - نتأكد من أن الصيغة PNG وأن المقاس 1024×1024، ثم نحفظ الملف باسم
v1.png. - نسجّل هذا الأصل في التطبيق، بحيث نأخذ منه الصورة الأصلية عند تعديل الصورة لاحقًا.
لا يمكن تخطي الخطوة الثالثة. فالدالة open() تقرأ رأس الملف فقط، أما ما إذا كانت بيانات الصورة مقطوعة فلن يظهر إلا عند استدعاء load().
2.2 GPT Image API: رفع الصورة الأصلية المحددة، وتغيير جسم الكوب فقط إلى الأحمر الطابوقي
الجولة الثانية تستدعي نقطة النهاية edits. نمرّر في data الحقول model وprompt وsize وquality وoutput_format، وفي files نرفع البايتات الحقيقية للملف v1.png عبر الحقل image[]. ومعنى الموجّه: غيّر جسم الكوب فقط إلى الأحمر الطابوقي، مع الإبقاء على شكل الكوب والمقبض والتكوين والإضاءة والخلفية دون تغيير.
في هذه الخطوة عدة نقاط يسهل الخطأ فيها:
- لا تمرّر
response_format. - لا تكتب رأس
Content-Typeيدويًا. فمكتبة requests تُنشئ تلقائيًا رأس multipart يحمل قيمة boundary، والكتابة اليدوية قد تضيع عليك قيمة boundary بدلًا من أن تحفظها. - لا ترفع سلسلة base64 على أنها ملف؛ فالذي يجب رفعه هو البايتات الأصلية للصورة.
بعد الانتهاء من التعديل، فكّ الترميز وتحقق من الناتج بالطريقة نفسها، ثم احفظه باسم v2.png. يجب الإبقاء على v1، وفي الوقت نفسه تدوين parent_asset_id = v1 في سجل الأصل. هذه العلاقة بين الأب والابن هي ما يعادل «السياق متعدد الجولات» في البنية الجديدة. وينبغي الانتباه أيضًا إلى أن هذا تعديل توليدي، فالنموذج سيحرص قدر الإمكان على الحفاظ على المناطق الأخرى، لكنه لا يضمن تطابق البكسلات واحدًا واحدًا خارج جسم الكوب.
فيما يلي مثال كامل بأقل قدر من الخطوات (مثال من التوثيق، لم يُختبر عمليًا في هذه المقالة):
import base64
import io
import os
import uuid
import requests
from PIL import Image
BASE_URL = "https://api.apiyi.com/v1" # نقطة النهاية الموحدة لـ APIYI
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# مهلة متوسطة في المثال؛ عدّلها وفق شبكتك ومستوى الجودة. لا إعادة محاولة تلقائية.
TIMEOUT = (10, 360)
assets = {} # معرف الأصل -> {"path": ..., "parent_asset_id": ...}
def decode_and_check(resp, path):
resp.raise_for_status()
item = resp.json()["data"][0]
b64 = item.get("b64_json")
if not b64:
raise ValueError("no b64_json in response, check body before any resend")
raw = base64.b64decode(b64, validate=True)
img = Image.open(io.BytesIO(raw))
img.load()
if img.format != "PNG" or img.size != (1024, 1024):
raise ValueError(f"unexpected image: {img.format} {img.size}")
with open(path, "wb") as f:
f.write(raw)
return path
def save_asset(path, parent_asset_id=None):
asset_id = str(uuid.uuid4())
assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
return asset_id
# الجولة 1: تحويل النص إلى صورة عبر JSON
gen_resp = requests.post(
f"{BASE_URL}/images/generations",
headers=HEADERS,
json={
"model": MODEL,
"prompt": (
"Light gray background, a blue ceramic mug centered, "
"handle facing right, soft side lighting, no text."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))
# الجولة 2: تعديل الصورة الأصلية المحددة صراحةً عبر multipart
selected_id = v1_id # إذا كانت النسخة المستهدفة لدى المستخدم غير واضحة، فاسأل أولاً
with open(assets[selected_id]["path"], "rb") as f:
edit_resp = requests.post(
f"{BASE_URL}/images/edits",
headers=HEADERS, # لا تعيّن Content-Type يدويًا؛ مكتبة requests تضبط boundary
data={
"model": MODEL,
"prompt": (
"Change only the mug body to brick red. Keep the mug shape, "
"handle, composition, lighting and background unchanged."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
files={"image[]": ("v1.png", f, "image/png")},
timeout=TIMEOUT,
)
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)
إن timeout=(10, 360) في المثال مجرد إعداد متوسط في التوثيق؛ أما القيمة الفعلية فتعتمد على مسار شبكتك ومستوى جودة الصورة. كما تعمّد المثال عدم تنفيذ إعادة محاولة تلقائية، والسبب موضح في القسم 3.2.
🚀 تحقق سريع: عيّن
APIYI_KEYإلى الرمز المميز الذي أنشأته في لوحة تحكم APIYI على apiyi.com، وسيكمل السكربت أعلاه دورتي العملية. يمكن للمستخدمين الجدد استخدام حصة الاختبار المجانية أولًا للتأكد من منطق التوجيه والتحليل، ثم الانتقال إلى حركة الإنتاج.

3 كيف نتحقق من القبول ونطابق الحسابات بعد ترحيل GPT Image API
3.1 المراحل الأربع لقبول صور GPT Image API
لا يمكن وسم صورة بأنها «قابلة للاستخدام» داخل التطبيق إلا بعد اجتياز المراحل الأربع كلها:
- نجاح HTTP: لم يرفع
raise_for_status()أي استثناء. - قابلة للفك: نجح فك ترميز base64 الصارم، ونجح
load()في Pillow. - المواصفات صحيحة: التنسيق والأبعاد مطابقة للطلب، وفي هذا المثال PNG و1024×1024.
- حدث التغيير البصري فعلاً: تحوّل جسم الكوب في v2 بالفعل إلى الأحمر الطوبي، مع بقاء شكل الكوب والمقبض والتكوين والخلفية على حالها تقريبًا.
المرحلة الرابعة تتطلب فحصًا بشريًا أو خطوة مراجعة منفصلة، لأن رمز حالة HTTP لا يكشف ما إذا كان النموذج قد عدّل الصورة بشكل صحيح. الصور التي تجتاز المراحل الثلاث الأولى فقط تُعد «صالحة تقنيًا» في أفضل الأحوال، ولا يمكن تسليمها بعد. وإذا لم تكن الاستجابة تحتوي على صورة أصلاً، فينبغي فحص محتوى الاستجابة أولاً قبل تحديد ما إذا كان يجب إعادة المحاولة؛ وقد ناقش مركز المساعدة هذا الموضوع في مقال مستقل، ولن نعيده هنا.
3.2 تكلفة الأدوات القديمة في GPT Image API وتكلفة كل صورة مقبولة
تختلف طريقة احتساب الفاتورة قبل الترحيل وبعده:
| البند | مسار Responses image_generation القديم | واجهة Images API المستقلة |
|---|---|---|
| الرسوم الإضافية | حوالي $0.20 كرسوم إضافية لاستدعاء أداة الصور في APIYI | لا توجد رسوم أداة كهذه |
| معنى هذا الرقم | يشير فقط إلى رسوم الأداة الإضافية هذه، وليس سعر الفاتورة الكاملة، ولا سعر OpenAI العام | تُحتسب حسب الاستخدام |
| الطريقة المناسبة للمقارنة | المقارنة بحسب «تكلفة كل صورة مقبولة» | المقارنة بحسب «تكلفة كل صورة مقبولة» |
لا تقارن السعر لكل وحدة فقط، بل يُنصح بتوحيد الحساب وفق الصيغة التالية:
تكلفة كل صورة مقبولة = الرسوم الفعلية المرتبطة (بما في ذلك استدعاءات النص المطلوبة، والطلبات الفاشلة التي تم خصمها، وإعادات المحاولة) ÷ عدد الصور التي اجتازت القبول
يجب أن يشمل البسط كل الرسوم المرتبطة، بما في ذلك استدعاءات المحادثة لتحديد النية، والطلبات الفاشلة التي تم خصمها، وإعادات المحاولة. أما المقام فيحتسب فقط الصور التي اجتازت الشروط الأربعة في القسم 3.1. وإذا لم تجتز أي صورة، فلا تحسب تكلفة الصورة الواحدة، لأن الاستنتاج في هذه الحالة ينبغي أن يكون «هناك مشكلة في سير العمل» وليس «سعر الوحدة مرتفعًا». ومقدار ما يمكن توفيره من الترحيل يعتمد على معدل إعادات المحاولة ومعدل اجتياز القبول، ولا تقدم هذه المقالة نسبًا محددة.
تأتي بيانات مطابقة الحسابات من سجل الاستهلاك في لوحة التحكم، حيث تكون سجلات الاستهلاك بالحقل type=2. وإذا كنت تقرأ حقل quota، فحوّله إلى مبلغ وفق وثائق المنصة باستخدام quota ÷ 500000.
يجب الانتباه خصوصًا إلى معالجة انقطاع الاتصال. نقطة نهاية الصور المستقلة تعيد النتيجة بشكل متزامن، وعند انقطاع الاتصال في منتصف الطريق قد تكون هذه الطلب قد خُصم بالفعل، ولا يمكن استرجاع الصورة عبر request ID. الترتيب الصحيح هو: أولاً تحقق من سجل الاستهلاك في لوحة تحكم APIYI على apiyi.com لمعرفة ما إذا كان هذا الطلب قد خُصم، ثم قرر ما إذا كنت بحاجة إلى إعادة الإرسال. ولهذا السبب لا يحتوي كود المثال على إعادة محاولة تلقائية، إذ إن إعادة المحاولة التلقائية قد تسبب خصمًا مكررًا عند انقطاع الاتصال. وإذا واجهت تحديد معدل أو احتجت إلى تبديل القناة، فيمكنك الرجوع إلى مقالة مركز المساعدة حول اختيار القناة وتخفيف خطأ 429.
معيار التحقق من اكتمال الترحيل واضح ومباشر: المحادثة النصية تعمل كالمعتاد؛ والجولة الأولى من توليد الصور تعيد بشكل مستقر v1 الذي يجتاز الشروط الأربعة؛ وكل تعديل على الصورة يمكن العثور عليه في سجل الأصول عبر parent_asset_id صريح؛ وكل خصم لصور في سجل لوحة التحكم يمكن ربطه بصورة مقبولة، أو فشل معروف، أو إعادة إرسال موثقة. وبعد تحقق هذه البنود، يمكن تحويل ما تبقى من حركة توليد الصور عبر Responses إلى Images API. وعند الحاجة إلى اختبار مقارنة بين عدة نماذج، توفر APIYI على apiyi.com واجهة موحدة متوافقة مع OpenAI، ويكفي عند تبديل النموذج تغيير معامل واحد هو MODEL.
المراجع
-
تحديث وثائق APIYI: نماذج الصور عبر الوكيل الرسمي تنتقل إلى Images API
- الرابط:
docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api - الشرح: معرّفات النماذج الخمسة عبر الوكيل الرسمي، ونقطتا النهاية المستقلتان، وسبب عدم التوصية بالمسار القديم
- الرابط:
-
الأسئلة الشائعة من APIYI: معالجة النصوص والصور معًا في API واحد
- الرابط:
docs.apiyi.com/faq/text-and-image-in-one-api - الشرح: أسلوب الجمع بين نموذج المحادثة الذي يستنتج النية، والتطبيق الذي يستدعي Images API بشكل منفصل
- الرابط:
-
دليل OpenAI لتوليد الصور
- الرابط:
developers.openai.com/api/docs/guides/image-generation - الشرح: أسلوب التحرير التتابعي في Responses وبنية الاستجابة
- الرابط:
-
APIYI GPT Image 2: تحويل النص إلى صورة / تحرير الصور
- الرابط:
docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image - الرابط:
docs.apiyi.com/api-capabilities/gpt-image-2/image-edit - الشرح: معاملات الطلب، والرفع عبر multipart، وأمثلة فحص فك الترميز
- الرابط:
-
أداة الصور في Responses من APIYI / أفضل ممارسات واجهة الصور / استعلام السجلات
- الرابط:
docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool - الرابط:
docs.apiyi.com/api-capabilities/image-api-best-practices - الرابط:
docs.apiyi.com/api-capabilities/log-query - الشرح: أساس حساب رسوم الأدوات، والتعامل مع انقطاع الاتصال، وتحويل سجلات الاستهلاك
- الرابط:
المؤلف: فريق APIYI التقني
التواصل التقني: إذا صادفت مشاكل في التوجيه أو الفواتير أثناء الترحيل، يسعدنا أن تتواصل معنا عبر الصفحة الرئيسية لـ APIYI على apiyi.com، ولمزيد من تفاصيل الواجهات يمكنك مراجعة مركز الوثائق docs.apiyi.com
