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

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

جرّب Apidog اليوم

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

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

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

قبل تنفيذ أول طلب، جهّز ما يلي:

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

قم بتصدير مفتاحك في الطرفية ليستمر في جميع الأمثلة:

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

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

نقطة النهاية الأساسية:

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

أضف الترويسة Authorization: Bearer $OPENAI_API_KEY وجسم JSON يتضمن معرف النموذج (model)، الموجه (prompt)، ومعلمات الضبط الأخرى.

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

استجابة النجاح تتضمن مصفوفة data للصور. في حال الفشل، تحقق من كود الخطأ والرسالة لتحديد السبب.

معلمات الطلب

تحديد المعلمات بشكل صحيح يؤثر على التكلفة والنتائج. الجدول التالي يلخص جميع المعلمات المدعومة:

المعلمة	النوع	القيم	ملاحظات
model	سلسلة نصية	gpt-image-2	مطلوب.
prompt	سلسلة نصية	حتى 32,000 حرف	مطلوب. المطالبات الطويلة تستهلك رموز إدخال أكثر.
size	سلسلة نصية	1024x1024, 1024x1536, 1536x1024, 2000x1000, 1000x2000, 2000x667, 667x2000	تحدد عدد رموز الإخراج والتكلفة.
quality	سلسلة نصية	standard, high	high أغلى (~2x) لكنها تعالج النصوص الدقيقة أفضل.
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):

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 أو تخزين سحابي.

مثال 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 الخام، حيث يتولى إدارة إعادة المحاولة، الرؤوس، والتغييرات التخطيطية.

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

معامل thinking يحدد مقدار التخطيط الذي يجريه النموذج قبل توليد الصورة:

• off: أسرع وأرخص. مناسب للمطالبات الإبداعية العامة.
• low: تخطيط خفيف. لجودة صور المنتجات/البطل.
• medium: تخطيط أثقل. مثالي للرسوم البيانية والمخططات الدقيقة.
• high: أقصى تخطيط. استخدمه فقط للتصاميم المعقدة أو متعددة اللغات.

قاعدة عملية: وجود أرقام أو تسميات أو قيود موضعية بالموجه = استخدم medium أو high.

التكلفة تزيد مع thinking. راجع صفحة تسعير OpenAI لتقدير التكلفة حسب الإعدادات.

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

حدد n > 1 للحصول على صور متعددة متسقة في استجابة واحدة:

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",
)

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

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

• b64_json: مناسب للمعالجة البرمجية المحلية. استجابة قد تكون ضخمة للصور الكبيرة.
• url: الصورة تُخزن مؤقتًا على CDN الخاص بـ OpenAI لمدة ساعة. قم بتنزيلها فورًا وادفعها إلى تخزينك السحابي.

لا ترسل روابط OpenAI مباشرة للمستخدمين النهائيين. قم بالتحميل إلى S3 أو R2 أو Cloudflare Images أولاً.

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

تعامل مع الأخطاء الشائعة كما يلي:

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	ارتفاع في الطلب على مستوى المنطقة	انتظر وأعد المحاولة.

في الطبقة 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 لتحسين تدفق العمل وتوفير الوقت.

سير عمل سريع في Apidog:

1. أنشئ طلبًا جديدًا (POST) إلى https://api.openai.com/v1/images/generations.
2. أضف ترويسة Authorization: Bearer {{OPENAI_API_KEY}}؛ خزن المفتاح في متغير بيئة.
3. الصق جسم الطلب JSON. Apidog يتحقق من صحة الحقول قبل الإرسال.
4. اضغط إرسال. استعرض النتائج مباشرة، واحفظ الجيد منها وقارن المتغيرات.
5. احفظ بيئات مختلفة لمقارنة مستويات thinking لنفس الموجه.

ميزة مقارنة الطلبات في Apidog تسهل اختبار المعلمات واستقرار النتائج. قم بتعديل معلمة واحدة وشاهد الفرق فورًا.

إذا كنت تستخدم Postman أو أي عميل HTTP عام، يمكنك تحميل Apidog وربطه بمفتاح OpenAI خلال أقل من خمس دقائق. للمزيد، راجع دليل اختبار API بدون Postman واستخدام Apidog في VS Code.

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

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

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

ما الفرق بين gpt-image-2 وgpt-image-1؟ نقطة النهاية والمصادقة نفسها. المعلمات الجديدة هي thinking، قيم size إضافية، وn حتى 10. تكامل SDK الحالي يستمر بالعمل بعد تغيير معرف النموذج. للمقارنة الكاملة: نظرة عامة على ChatGPT Images 2.0.

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

هل تدعم واجهة API تحرير الصور أو inpainting؟ نقاط نهاية التحرير والتنوع متاحة تحت نفس النمط مع معرف النموذج الجديد. راجع مرجع نموذج gpt-image-2 للمعلمات المدعومة.

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

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

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