كيفية استخدام API gpt-image-2؟

إن واجهة برمجة التطبيقات (API) gpt-image-2 هي نقطة نهاية OpenAI الجديدة لتوليد الصور، والتي تم إطلاقها جنبًا إلى جنب مع ChatGPT Images 2.0 في 21 أبريل 2026. إذا كنت تستدعي بالفعل واجهات برمجة تطبيقات الدردشة أو التضمينات من OpenAI، فإن إضافة توليد الصور يتطلب شكل طلب جديد واحد، ومفتاح API بالنطاق الصحيح، وحوالي عشر دقائق.

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

بحلول النهاية، سيكون لديك استدعاءات عاملة، ومجموعة Apidog قابلة لإعادة الاستخدام للتكرار، وصورة واضحة لتكلفة كل معلمة.

زر

المتطلبات الأساسية

قبل طلبك الأول تحتاج إلى أربعة أشياء:

حساب OpenAI مع إمكانية الوصول إلى API. حسابات المطورين منفصلة عن ChatGPT Plus؛ اشتراك ChatGPT لا يتضمن أرصدة API.
طبقة استخدام قابلة للفوترة. يتوفر gpt-image-2 في الطبقة 1 وما فوق. تبدأ الحسابات الجديدة بالطبقة المجانية ويجب إضافة الدفع قبل إلغاء قفل نقاط نهاية الصور.
مفتاح API بنطاق images:write. يوصى باستخدام مفاتيح ذات نطاق مشروع على المفاتيح ذات نطاق المستخدم للإنتاج.
أداة اختبار تعرض معاينات استجابات الصور. يعمل `curl` الطرفي للطلب الأول؛ بعد ذلك، استخدم عميل API حقيقي. المزيد عن ذلك أدناه.

عيّن المفتاح مرة واحدة في محطتك الطرفية بحيث يعمل كل مثال في هذا الدليل دون تعديلات:

export OPENAI_API_KEY="sk-proj-..."

نقطة النهاية والمصادقة

يستخدم gpt-image-2 نفس نقطة نهاية توليد الصور التي استخدمها النموذج السابق:

POST https://api.openai.com/v1/images/generations

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

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A sharp product hero image for an API testing platform, dark background",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

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

معلمات الطلب

كل حقل في جسم الطلب يغير ما تدفعه وما تحصل عليه. إليك خريطة المعلمات الكاملة لـ gpt-image-2.

المعلمة	النوع	القيم	ملاحظات
`model`	سلسلة نصية	`gpt-image-2`	مطلوب.
`prompt`	سلسلة نصية	حتى 32,000 حرف	مطلوب. المطالبات الأطول تستهلك المزيد من رموز الإدخال.
`size`	سلسلة نصية	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	يحدد عدد رموز الإخراج.
`quality`	سلسلة نصية	`standard`, `high`	تكلفة `high` حوالي 2× ولكنها تتعامل مع النص الدقيق وعناصر واجهة المستخدم.
`n`	عدد صحيح	1–10	الطلبات الدفعية تشترك في النمط عبر المجموعة.
`thinking`	سلسلة نصية	`off`, `low`, `medium`, `high`	ميزانية التفكير قبل العرض.
`response_format`	سلسلة نصية	`url`, `b64_json`	عناوين URL تنتهي صلاحيتها في ساعة واحدة.
`user`	سلسلة نصية	نص حر	يستخدم للكشف عن إساءة الاستخدام؛ قم بتمرير معرف مستخدم مشفر.
`background`	سلسلة نصية	`auto`, `transparent`, `opaque`	يتم إرسال الإخراج الشفاف كـ PNG مع قناة ألفا.
`seed`	عدد صحيح	أي int32	تحكم فضفاض؛ نفس البذرة بالإضافة إلى نفس الموجه قريبان، وليسا متطابقين.

المعلمات الثلاثة التي تغير التكلفة بشكل كبير هي size وquality وthinking. يمكن أن تكلف صورة بجودة high وعرض 2000 بكسل مع thinking: "high" ما بين 4 إلى 5 أضعاف التكلفة الأساسية لعرض 1024x1024 بجودة standard.

مثال بايثون

يضيف SDK الرسمي (openai>=1.50.0) دعمًا أصليًا لـ gpt-image-2:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "A minimalist diagram of an OAuth 2.1 authorization code flow with PKCE. "
        "Five boxes labeled in English: User, Client, Auth Server, Resource Server, Token. "
        "Sharp sans-serif text, off-white background, teal accent arrows."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Generated {len(response.data)} images into {out_dir.resolve()}")

شيئان جديران بالذكر:

response.data هي قائمة حتى عندما يكون n=1. كرر دائمًا.
b64_json أسهل للسكربتات المحلية؛ url أفضل عندما تقوم بإعادة توجيه الصورة إلى CDN أو تحميل S3، حيث أنك تتخطى دورة فك التشفير ثم إعادة التشفير.

مثال Node.js / TypeScript

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI mockup for a REST client, sentence-case labels, latency sparkline in the top-right, cool grey palette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Saved ${response.data.length} images`);

استخدم SDK الرسمي بدلاً من fetch الخام ما لم يكن لديك سبب لعدم القيام بذلك. يتعامل SDK مع إعادة المحاولة، ورؤوس التكرارية، والتدفق، ويتتبع التغييرات المخططية التي تسبب أعطالاً بين مراجعات النموذج.

وضع التفكير: متى تستخدمه

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

off: لا يوجد تفكير. الأسرع والأرخص، والأفضل للمطالبات الإبداعية الفضفاضة حيث لا يجب أن يكون التكوين دقيقًا.
low: تخطيط خفيف. خيار جيد للصور المنتجات وصور البطل.
medium: تخطيط أثقل. الخيار الصحيح للرسوم البيانية، والرسوم المعلوماتية، والشرائح، وأي شيء يحتوي على عناصر معدودة ("أربع لوحات"، "ثلاثة أسهم").
high: أقصى قدر من التفكير. يؤتي ثماره فقط في التصميمات المعقدة متعددة اللغات أو الرسوم البيانية الفنية الدقيقة؛ توقع زمن استجابة وتكلفة أعلى بشكل ملحوظ.

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

يضيف وضع التفكير رموزًا للتفكير إلى الفاتورة بالإضافة إلى رموز إخراج الصورة. تسرد صفحة تسعير OpenAI الأسعار الحالية لكل رمز؛ خصص ميزانية تزيد بمقدار 1.2-2x عن تكلفة صورتك الأساسية عندما يكون وضع medium أو high قيد التشغيل.

التوليد الدفعي

يؤدي تعيين n > 1 إلى إرجاع صور متعددة في استجابة واحدة تشترك في التركيب والنمط. هذا ليس هو نفسه استدعاء نقطة النهاية n مرة بشكل متوازٍ؛ فهذا يمنحك أربع صور غير مرتبطة. الإخراج الدفعي متماسك، وهو ما يتوافق مع كيفية تكرار فريق التصميم.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Four different hero illustrations for an API documentation landing page, shared color palette, shared line weight.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

تدفع لكل صورة، لذا تكلفة n=4 تبلغ تقريبًا 4 أضعاف تكلفة n=1. الفائدة هي الاتساق، وليس الإنتاجية.

تنسيق الاستجابة والتخزين

تنسيقان، حالتا استخدام:

b64_json: الصورة مضمنة في الاستجابة. سهل للسكربتات. حمولات الاستجابة تصبح كبيرة بسرعة؛ يمكن أن تدفع صورة PNG عالية الجودة بعرض 2000 بكسل حجم الاستجابة إلى أكثر من 3 ميجابايت.
url: الصورة تبقى على CDN الخاص بـ OpenAI لمدة ساعة واحدة، وتقوم بتنزيلها بنفسك. أفضل للدوال بدون خادم ذات حدود حجم الاستجابة ولخطوط الأنابيب التي تعيد توجيه الصورة إلى التخزين الخاص بك.

للانتاج، قم بتنزيل عنوان URL ودفعه إلى سلة S3 أو R2 أو Cloudflare Images الخاصة بك على الفور. لا ترسل عناوين URL الخاصة بـ OpenAI للمستخدمين النهائيين؛ فهي تنتهي صلاحيتها.

معالجة الأخطاء وحدود المعدل

يعيد gpt-image-2 أشكال أخطاء OpenAI القياسية. إليك الأخطاء التي ستواجهها:

HTTP	`code`	السبب	الإصلاح
400	`invalid_request_error`	حجم سيء، نسبة غير مدعومة، موجه يتجاوز 32 ألف حرف	تحقق من قائمة الأحجام واختصر الموجه.
401	`invalid_api_key`	مفتاح مفقود أو خاطئ	أعد تصدير `OPENAI_API_KEY`.
403	`insufficient_quota`	لا توجد أرصدة، أو طبقة مجانية	أضف الفواتير، تحقق من الطبقة.
429	`rate_limit_exceeded`	عدد كبير جدًا من الطلبات في الدقيقة	تراجع مع التذبذب؛ أعد المحاولة باستخدام `Retry-After`.
429	`image_generation_user_error`	رفض سياسة المحتوى	أعد صياغة الموجه.
500	`server_error`	مشكلة عابرة في OpenAI	أعد المحاولة مرتين مع تراجع أسي.
503	`overloaded`	ارتفاع في الطلب على مستوى المنطقة	انتظر وأعد المحاولة.

حدود المعدل على gpt-image-2 تعتمد على الطبقة. في الطبقة 1، تبدأ بحوالي 50 طلبًا في الدقيقة؛ الطبقات الأعلى تتوسع. اقرأ دائمًا ترويسات x-ratelimit-remaining-requests و x-ratelimit-remaining-tokens على كل استجابة وخفض السرعة قبل أن تصل إلى الحد الأقصى.

الأخطاء القابلة لإعادة المحاولة في الإنتاج:

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

لا تعاود المحاولة في حالة أخطاء 400، 401، أو 429 المتعلقة بسياسة المحتوى؛ فهذه الأخطاء تحدث لسبب ما، وتكرار المحاولة يهدر الأرصدة.

اختبار واجهة برمجة التطبيقات باستخدام Apidog

التكرار على مطالبات توليد الصور من الطرفية بطيء: لا يمكنك رؤية النتيجة، ولا يمكنك مقارنة تغييرات المعلمات، ولا يمكنك حفظ إصدارات المطالبات الجيدة. يحل عميل API مصمم خصيصًا هذه المشكلات الثلاث.

يعامل Apidog نقطة نهاية gpt-image-2 كطلب من الدرجة الأولى. سير العمل النموذجي:

أنشئ طلبًا جديدًا في مجموعة OpenAI الخاصة بك، بطريقة POST، وعنوان URL https://api.openai.com/v1/images/generations.
أضف Authorization: Bearer {{OPENAI_API_KEY}} كعنوان؛ عيّن OPENAI_API_KEY في متغير بيئة بحيث لا يظهر أبدًا في الكود المصدري.
الصق جسم JSON مع موجهك؛ Apidog يتحقق من مواصفات OpenAPI ويظهر عدم تطابق الأنواع قبل الإرسال.
اضغط على إرسال. يتم عرض استجابات الصور مضمنة؛ احفظ الجيدة منها، ووسم السيئة، وقم بعمل نسخة من الطلب للمتغيرات.
احفظ البيئات لـ thinking: off و thinking: medium و thinking: high لمقارنة نفس الموجه عبر مستويات التفكير.

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

إذا كنت قادمًا من عميل HTTP عام أو مساحة عمل Postman متعطلة، قم بتنزيل Apidog ووجهه إلى مفتاح OpenAI الخاص بك؛ يستغرق الإعداد أقل من خمس دقائق. يمكن للفرق التي تقيم البدائل أيضًا قراءة دليل اختبار API بدون Postman ونظرة عامة على ملحق Apidog لـ VS Code.

المزالق الشائعة

عدد قليل من الأخطاء تهدر الأرصدة والوقت في الأسبوع الأول مع gpt-image-2.

استخدام quality: "standard" للمطالبات التي تحتوي على نصوص كثيرة. الجودة القياسية تشوه النصوص الصغيرة. انتقل إلى high عندما تكون التسميات، الأيقونات، أو نصوص واجهة المستخدم مهمة.
الإفراط في المطالبات. 32 ألف حرف هو الحد الأقصى، وليس الهدف. بعد بضع مئات من الرموز، يبدأ النموذج في تجاهل التعليمات السابقة. اجعل المطالبات أقل من 500 كلمة واستخدم thinking لفرض قيود معقدة.
توقع التكرارية من seed. يقلل Seed التباين ولكنه لا يثبت الإخراج. إذا كنت بحاجة إلى نفس الصورة بالضبط، فقم بتخزين البايتات مؤقتًا؛ لا تعيد توليدها.
شحن عناوين URL الخاصة بـ OpenAI. تنتهي صلاحيتها في ساعة واحدة. قم دائمًا بنسخها إلى التخزين الخاص بك قبل تقديمها للمستخدمين النهائيين.
استدعاء نقطة النهاية في حلقة ضيقة. توليد الصور بطيء. قم بالموازاة عبر العمال واحترم ترويسات حد المعدل؛ الحلقات الضيقة المتسلسلة تؤدي فقط إلى الانتظار وانتهاء المهلة.

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

كيف يختلف gpt-image-2 عن gpt-image-1 على مستوى واجهة برمجة التطبيقات؟نقطة النهاية نفسها، المصادقة نفسها. معلمات جديدة: thinking (off/low/medium/high)، قيم size إضافية تصل إلى 2000 بكسل، و n حتى 10 مع نمط مشترك. تستمر عمليات تكامل SDK الحالية في العمل بعد تبديل معرف النموذج؛ ما عليك سوى إضافة المعلمات الجديدة حيثما تساعد. للاطلاع على الفروق الكاملة، راجع نظرة عامة على ChatGPT Images 2.0.

ما هي أسرع طريقة لإنشاء نموذج أولي لتكامل gpt-image-2؟أنشئ طلبًا في Apidog، واحفظ بيئتين (قياسية مقابل التفكير)، وكرر المطالبات دون لمس الكود. قم بتصدير الطلب النهائي كـ `curl` أو كود SDK عندما تكون مستعدًا للتنفيذ.

هل تدعم واجهة برمجة التطبيقات تحرير الصور أو التلوين الداخلي (inpainting)؟تتبع نقاط نهاية التحرير والتنوع نفس النمط الذي اتبعته الأجيال السابقة تحت معرف النموذج الجديد. تحقق من مرجع نموذج gpt-image-2 للحصول على أحدث مخطط؛ يتم توثيق معلمات الأقنعة وصور الإدخال هناك.

هل يمكنني استخدام gpt-image-2 للإنتاج التجاري؟نعم، بموجب سياسات الاستخدام القياسية لـ OpenAI. أنت تمتلك الصور المُولدة؛ تحتفظ OpenAI بالحق في استخدام المدخلات والمخرجات لمراقبة سوء الاستخدام. الشخصيات ذات العلامات التجارية والشخصيات العامة المعروفة لا تزال تثير الحواجز الوقائية.

ماذا عن تكلفة حمل العمل الإنتاجي؟بتكلفة حوالي 0.21 دولار للصورة عالية الجودة بحجم 1024×1024 في الوضع القياسي، فإن 10,000 صورة شهريًا تكلف حوالي 2,100 دولار بدون وضع التفكير. أضف 20-80% لوضع التفكير. قارن هذا بالبدائل المستضافة ذاتيًا مثل دليل API لـ GLM 5V Turbo وتكامل Qwen 3.5 Omni إذا كانت الميزانية أهم من جودة الذروة.

هل يوجد بديل أرخص بنفس جودة عرض النص؟ليس بعد بنفس الجودة للنصوص متعددة اللغات. لقد قلصت النماذج مفتوحة الوزن الفجوة في التكوين ولكنها لا تزال متخلفة في النصوص الصينية واليابانية والكورية (CJK) والهندية.

زر