شرح قيود رفع الصور في APIYI لنموذج gpt-image-2: 50 ميجابايت للصورة الواحدة، بحد أقصى 16 صورة، و5 نصائح عملية لتجنب الأخطاء

يواجه العديد من المطورين عند دمج واجهة تحرير الصور في gpt-image-2 مشكلة متكررة: فبعد البحث في صفحة مرجع API الخاص بـ images/edit، يجدون فقط عبارة "يمكن لنموذج GPT image استقبال ما يصل إلى 16 صورة"، ولكنهم لا يجدون أي ذكر لحدود حجم الصورة الواحدة. هل يعني ذلك عدم وجود قيود؟ أم أن التوثيق ناقص؟

الإجابة هي: القيود موجودة وواضحة تماماً، وهي أن حجم الصورة الواحدة يجب أن يكون أقل من 50 ميجابايت، مع دعم صيغ PNG وWebP وJPG. تكمن المشكلة في أن هذه القاعدة لم تُدرج في جدول المعلمات بصفحة المرجع، بل ذُكرت في دليل استخدام "توليد الصور" (Image Generation) منفصل، مما أدى إلى تشتت المعلومات وتسبب في حيرة الكثيرين.

في هذا المقال، سنشرح بالتفصيل قيود رفع الصور في API الخاص بـ gpt-image-2: العدد، الحجم، الصيغ، قواعد القناع (mask)، وقيود الدقة، بالإضافة إلى قضية عملية أكثر أهمية من سقف الـ 50 ميجابايت، وهي: لماذا لا ننصحك فعلياً برفع صور بهذا الحجم.

قيود رفع الصور في API الخاص بـ gpt-image-2: المواصفات الرسمية الكاملة

لنضع الخلاصة في البداية. يستقبل gpt-image-2 الصور عبر نقطة النهاية v1/images/edits، والقيود الرسمية الكاملة موضحة في الجدول التالي:

جدول سريع لقيود رفع الصور في gpt-image-2

بند القيد	المواصفات الرسمية	مصدر التوثيق
الحد الأقصى للصور في الطلب الواحد	16 صورة (نماذج GPT image)	مرجع API: images/edit
حجم الصورة الواحدة	< 50 ميجابايت	دليل استخدام توليد الصور
الصيغ المدعومة	PNG, WebP, JPG	دليل استخدام توليد الصور
طريقة رفع الصورة	`image_url` أو `file_id` (اختر واحدة)	مرجع API: images/edit
قناع التعديل (mask)	نفس صيغة وأبعاد الصورة الأصلية، < 50 ميجابايت، يجب أن يحتوي على قناة ألفا	دليل استخدام توليد الصور
عدد الصور الموّلدة في الطلب الواحد (n)	1-10 صور	مرجع API: images/edit

بمعنى آخر، نظرياً يمكن لطلب تعديل واحد أن يحمل ما يصل إلى 16 صورة يقترب حجم كل منها من 50 ميجابايت. لكن "الحد الأقصى النظري" يختلف عن "كيفية الاستخدام العملي"، وهو ما سنوضحه لاحقاً.

هناك نقطة هامة تستحق الذكر: تقبل المعلمة images في الإصدار الجديد من API مصفوفة من الكائنات، حيث يوفر كل كائن إما image_url أو file_id. يأتي file_id من الرفع المسبق عبر Files API، وهو مناسب لسيناريوهات مكتبة المواد القابلة لإعادة الاستخدام؛ بينما يدعم image_url عناوين الويب العامة أو base64 data URL، وهو مناسب للطلبات لمرة واحدة. وكلا الطريقتين تخضعان لقيد الـ 50 ميجابايت نفسه.

🎯 نصيحة للتحقق السريع: إذا لم تكن متأكداً مما إذا كانت صورك ستتجاوز القيود، فإن الطريقة المباشرة هي إرسال طلب حقيقي ومعاينة رسالة الخطأ. ننصح بإجراء اختبارات الحدود هذه عبر واجهات APIYI.com المتوافقة مع OpenAI، حيث تتيح لوحة سجلات المنصة رؤية حجم جسم الطلب وتفاصيل الخطأ بالكامل، مما يجعل استكشاف الأخطاء وإصلاحها أكثر وضوحاً مقارنة بالتعامل المباشر مع واجهة API الرسمية.

gpt-image-2 上传大小为什么在文档里"找不到"

回到开头的疑问：为什么 Reference 页面只写了 16 张，不写大小？这其实是 OpenAI 文档结构的设计取舍。images/edit 的 Reference 页面是按"参数 Schema"组织的，images 参数在 Schema 层面只是一个对象数组，数量上限属于数组约束，所以被写了进去；而文件大小、格式属于"运行时校验"，被归类到了 Image Generation 指南的叙述性文字里。

类似的"藏在指南里"的规则还有几条，做图片编辑功能前最好一并确认：

mask 蒙版三要求：必须与被编辑图片同格式、同尺寸，文件同样小于 50MB，且必须包含 alpha 通道——用 JPG 当 mask 是最常见的报错原因，因为 JPG 没有 alpha 通道。
分辨率不是任意的：gpt-image-2 的 size 参数支持自定义分辨率，但有硬约束——最长边不超过 3840px，宽高都必须是 16px 的倍数，宽高比不超过 3:1，总像素需落在 655,360 到 8,294,400 之间。
输入图会计费：edit 请求中的参考图按图像输入 token 计费，input_fidelity: high 时消耗的输入 token 会明显增加。

gpt-image-2 分辨率与 size 参数约束

约束维度	规则	示例
最长边	≤ 3840px	3840×2160（4K 横版）可用
边长对齐	宽高均为 16px 倍数	1024、1536、2048 均合法
宽高比	≤ 3:1	2048×1152 合法，3072×1024 合法
总像素	655,360 – 8,294,400	低于 768×854 量级会被拒
常用预设	1024×1024 / 1536×1024 / 2048×2048 / 3840×2160	竖版同理对调

如果你的业务需要频繁在不同分辨率之间切换，建议把这张约束表做成请求前的本地校验，在客户端就拦截非法尺寸，比等 API 返回 400 错误节省一次往返。在 APIYI apiyi.com 的文档中心也整理了 gpt-image-2 的参数校验清单，可以直接对照实现。

gpt-image-2 实战：50MB 是上限，1.5MB 才是甜点

在了解了 50MB 的硬上限后，更重要的问题是：在实际工程中应该上传多大的图片？我们的建议是：单张图片控制在 1.5MB 左右，尽量不超过 5MB。这不是拍脑袋决定的，背后有三层原因。

第一层是 base64 膨胀。如果你使用 data URL 方式内嵌图片，base64 编码会让体积膨胀约 33%——一张 40MB 的原图编码后接近 53MB，叠加 JSON 结构后，请求体可能直接超限。当 16 张图全部使用 base64 内嵌时，这个问题会被放大 16 倍，因此大体积素材务必改用 file_id 预上传通道。

第二层是传输与解码耗时。超过 5MB 之后，上传时间加服务端解码时间呈非线性增长，在网络波动时容易触发超时重试，反而拖慢整体出图速度。1.5MB 左右的图片在普通家庭宽带下 1-2 秒即可完成上传，是稳定性和质量的平衡点。

第三层是画质收益递减。gpt-image-2 在处理输入图时会先进行内部预处理，当输入分辨率远超输出分辨率时，多出来的像素基本被浪费。一张长边 3840px、压缩到 2MB 以内的 JPG，与 40MB 的无损 PNG 在编辑效果上几乎没有可感知差异，但成本和耗时却差了一个量级。

gpt-image-2 图片大小实践建议

原图情况	建议处理	预期效果
< 1.5MB	直接上传	最佳速度与稳定性
1.5MB – 5MB	可直接传，建议转 JPG/WebP	速度可接受
5MB – 20MB	压缩至长边 ≤ 3840px + 质量 85	画质几乎无损，耗时大幅下降
20MB – 50MB	必须压缩，改用 file_id 上传	避免 base64 膨胀超限
> 50MB	超出硬上限，必须压缩	否则直接报错

💡 批量场景提示：电商抠图、批量风格化这类高并发场景，建议在上传前用 sharp 或 Pillow 统一做"长边 3840px + JPG 质量 85"的预压缩。我们在 APIYI apiyi.com 的企业客户案例中验证过，这一步平均能把单次 edit 请求的端到端耗时降低 40% 以上，且画质投诉为零。

gpt-image-2 API 快速上手：多图编辑代码示例

gpt-image-2 遵循标准 OpenAI 接口协议，下面是一个携带多张参考图的最简编辑示例，通过 APIYI 转发只需替换 base_url：

import base64
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-apiyi-key",
    base_url="https://api.apiyi.com/v1"  # APIYI 统一接口
)

def to_data_url(path):
    with open(path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode()
    return f"data:image/jpeg;base64,{b64}"

result = client.images.edit(
    model="gpt-image-2",
    image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
    prompt="将产品图融合参考图的霓虹赛博风格,保持产品主体不变",
    input_fidelity="high",   # 高保真保留输入细节,输入 token 消耗更多
    size="2048x2048",
    quality="high"
)
print(result.data[0].b64_json[:64])  # 返回 base64 编码的结果图

几个参数要点：input_fidelity 设为 high 时人脸、Logo 等细节保留度显著提升，代价是图像输入 token 计费增加；quality 与 size 是决定输出成本的两个主要杠杆；n 参数单次最多生成 10 张。计费方面，gpt-image-2 按 token 计价：文本输入 $5/M，图像输入 $8/M（缓存命中 $2/M），图像输出 $30/M。换算成单张图，1024×1024 的 low 档约 $0.006，medium 档约 $0.05，high 档约 $0.21，输出侧永远是成本大头。

另外注意官方的速率限制按账户层级区分：Tier 1 仅 5 张图/分钟，Tier 4 为 150 张/分钟，Tier 5 为 250 张/分钟。新账户层级低，批量任务很容易撞限流。通过 APIYI apiyi.com 这类聚合平台调用可以绕开单账户层级限制，适合需要大并发出图的生产环境。

الفروقات في قيود الرفع بين gpt-image-2 والنماذج السابقة

إذا كنت تقوم بنقل مشروعك من gpt-image-1 أو DALL·E 2، فهناك بعض الفروقات الجيلية التي يجب الانتباه إليها. يكمن التغيير الأكبر في الانتقال من DALL·E 2 إلى سلسلة GPT image؛ حيث كانت واجهة التعديل (edit) في DALL·E 2 تقبل فقط صورة مربعة بصيغة PNG وبحجم أقل من 4 ميجابايت. أما مع سلسلة GPT image، فقد تم تخفيف القيود لتصل إلى 16 صورة، وبحجم 50 ميجابايت، وثلاث صيغ مختلفة. لذا، فإن منطق المعالجة المسبقة "PNG + ضغط 4 ميجابايت" المعتمد في العديد من المشاريع القديمة يمكن تبسيطه بشكل كبير بعد النقل.

أما ترقية gpt-image-2 مقارنة بـ gpt-image-1 فتتجلى بشكل رئيسي في الدقة والتكلفة. كان gpt-image-1 يدعم فقط ثلاثة أحجام مخرجات ثابتة (1024×1024، 1536×1024، 1024×1536)، بينما يتيح gpt-image-2 دقة مخصصة تصل إلى دقة 4K مع طول ضلع أقصى يبلغ 3840 بكسل. أما من حيث السعر، فقد انخفضت تكلفة إدخال الصور في gpt-image-2 من 10 دولارات لكل مليون إلى 8 دولارات، وانخفضت تكلفة مخرجات الصور من 40 دولاراً إلى 30 دولاراً لكل مليون، مع إضافة فئة جديدة بتكلفة 2 دولار لكل مليون عند مطابقة ذاكرة التخزين المؤقت، مما يقلل التكاليف بشكل ملحوظ في سيناريوهات الصور المرجعية المتكررة.

مقارنة قيود الرفع بين gpt-image-2 والنماذج السابقة

وجه المقارنة	DALL·E 2	gpt-image-1	gpt-image-2
عدد صور الإدخال	صورة واحدة	حتى 16 صورة	حتى 16 صورة
الحد الأقصى لحجم الصورة الواحدة	< 4 ميجابايت	< 50 ميجابايت	< 50 ميجابايت
صيغ الإدخال	PNG مربعة فقط	PNG/WebP/JPG	PNG/WebP/JPG
دقة المخرجات	صورة مربعة ثابتة	3 أحجام ثابتة	مخصصة، أقصى ضلع 3840 بكسل
تكلفة مخرجات الصور	حسب الصورة	$40/M tokens	$30/M tokens (ذاكرة مؤقتة $2/M)
input_fidelity	غير مدعوم	مدعوم	مدعوم، تفاصيل عالية الدقة أقوى

عند نقل الكود، يكفي عادةً تغيير معامل model فقط، ولكن يُنصح بتحديث استراتيجيات التحقق من الدقة والضغط وفقاً للجدول أعلاه. إذا كنت ترغب في التحقق من نتائج النقل قبل تعديل كود الإنتاج، يمكنك استخدام نفس مجموعة المواد على APIYI (apiyi.com) لاستدعاء النموذجين ومقارنة جودة التعديل وتكاليف الاستخدام فعلياً.

الأسئلة الشائعة حول رفع الصور في gpt-image-2

س1: ما هو الحد الأقصى لحجم الصورة الواحدة التي يمكن رفعها في gpt-image-2؟

الحد الأقصى هو 50 ميجابايت، ويدعم صيغ PNG وWebP وJPG. هذا القيد مذكور في دليل استخدام توليد الصور من OpenAI وليس في جدول معاملات المرجع (Reference) الخاص بـ images/edit، لذا قد لا تجده في صفحة المرجع. من الناحية العملية، يُنصح بالحفاظ على الحجم بين 1.5 و5 ميجابايت للحصول على أفضل تجربة.

س2: كيف يتم استخدام قيد الـ 16 صورة؟

يقبل معامل images ما يصل إلى 16 كائناً من الصور، حيث يتم تحديد كل صورة عبر image_url أو file_id. يتعامل النموذج مع الصور المتعددة كمرجع مشترك، وهو أمر مثالي لسيناريوهات التعديل التي تجمع بين "صورة المنتج + صورة النمط + مرجع التكوين". لاحظ أن الـ 16 صورة هي الحد الأقصى للإدخال، بينما يتم التحكم في عدد المخرجات عبر معامل n بحد أقصى 10 صور.

س3: ما سبب ظهور خطأ "invalid mask" عند استخدام قناع (mask)؟

في 90% من الحالات، يعود السبب إلى قناة ألفا (alpha channel). يجب أن يكون القناع بنفس صيغة وأبعاد الصورة المعدلة، ويجب أن يحتوي على قناة ألفا؛ وبما أن صيغة JPG لا تدعم قناة ألفا، يجب استخدام PNG للقناع. تمثل المناطق الشفافة "المناطق المسموح بإعادة رسمها"، بينما تبقى المناطق غير الشفافة كما هي.

س4: كيف أختار بين الرفع عبر base64 أو عبر file_id؟

بالنسبة للصور الصغيرة (< 5 ميجابايت) والطلبات لمرة واحدة، يعد استخدام base64 data URL هو الأسهل. أما للصور الكبيرة أو المواد التي تحتاج إلى استخدام متكرر، فاستخدم Files API للرفع المسبق والحصول على file_id؛ فهذا يتجنب تضخم حجم base64 بنسبة 33%، ويسمح بإعادة استخدام الصورة عبر طلبات متعددة. إذا كنت غير متأكد، يمكنك تجربة الطريقتين عبر لوحة تحكم APIYI (apiyi.com) ومقارنة وقت الاستجابة الفعلي قبل اتخاذ القرار.

ملخص: الأرقام الثلاثة الحاسمة لقيود الرفع في gpt-image-2

بالعودة إلى سؤالنا الأساسي، يمكن تلخيص قيود الرفع الخاصة بـ API تحرير الصور gpt-image-2 في ثلاثة أرقام: 16 صورة (الحد الأقصى لعدد الصور في المدخلات الواحدة، كما هو مذكور في المرجع)، 50 ميجابايت (الحد الأقصى لحجم الصورة الواحدة، كما هو مذكور في دليل الاستخدام)، و1.5 ميجابايت (الحجم المثالي للتطبيقات العملية). إن قيام التوثيق الرسمي بتقسيم معلومات العدد والحجم على صفحتين هو السبب الرئيسي وراء الارتباك الذي يجعل البعض يظن أن الحد هو "16 صورة فقط".

أما نصائح التنفيذ فهي بسيطة للغاية: قبل الرفع، قم بضغط الصور بحيث لا يتجاوز طول الضلع الأطول 3840 بكسل، مع ضبط جودة JPG عند 85 تقريبًا؛ بالنسبة لـ mask، استخدم دائمًا صيغة PNG مع قناة ألفا (alpha channel)؛ أما المواد الكبيرة، فاستخدم مسار file_id. إذا جعلت هذه الخطوات الثلاث جزءًا من المعالجة المسبقة الثابتة قبل إرسال الطلب، فستتخلص فعليًا من جميع الأخطاء المتعلقة بالرفع.

إذا كنت بحاجة إلى استدعاء gpt-image-2 بشكل مستقر داخل الصين، أو ترغب في رفع سقف حدود الاستخدام إلى مستوى الإنتاج، يمكنك الوصول عبر الواجهة الموحدة لـ APIYI (apiyi.com)، حيث تتوافق الخدمة مع مكتبة OpenAI SDK الأصلية، ويمكنك الانتقال إليها بمجرد تغيير سطر واحد في base_url.

المراجع: مرجع OpenAI API: developers.openai.com/api/reference/resources/images/methods/edit

المؤلف: فريق APIYI
نركز على تجميع واجهات برمجة تطبيقات نماذج اللغة الكبيرة (AI) وأفضل الممارسات. للمزيد من تقييمات النماذج وأدلة الربط، تفضل بزيارة APIYI على apiyi.com.

شرح قيود رفع الصور في APIYI لنموذج gpt-image-2: 50 ميجابايت للصورة الواحدة، بحد أقصى 16 صورة، و5 نصائح عملية لتجنب الأخطاء