تفسير عميق لـ imagegen-demo مفتوح المصدر من OpenAI: 4 خطوات للوصول إلى واجهة برمجة تطبيقات gpt-image-2 الرسمية

ملاحظة من المؤلف: أطلقت OpenAI رسميًا مشروع Photobooth التجريبي القائم على gpt-image-2. في هذا المقال، سنقوم بتفكيك الكود المصدري ومبدأ عمل البث المباشر (Streaming) بعمق، وسنشرح كيفية إعادة إنتاج هذه القدرات دون أي عوائق تقنية عبر قناة وكيل APIYI.

أطلقت OpenAI رسميًا مشروع openai-imagegen-demo على GitHub، وهو تطبيق تجريبي مبني بإطار Next.js تم إصداره بالتزامن مع gpt-image-2. يستعرض هذا التطبيق قدرات النموذج الفريدة مثل توليد الصور بالبث المباشر، أسلوب البورتريه، والتوليد المتزامن متعدد الأنماط. رابط المشروع: github.com/openai/openai-imagegen-demo.

هذا ليس مجرد مثال "Hello World" تقليدي؛ فالكود المصدري يخفي خلفه نمط الإخراج التدريجي partial_images الموصى به من قبل OpenAI، بالإضافة إلى أحدث طرق استخدام نقطة النهاية /v1/images/edits في سيناريوهات تحرير الصور المتعددة.

القيمة الجوهرية: بعد قراءة هذا المقال، ستفهم تمامًا بنية هذا العرض التوضيحي الرسمي، والمعايير الرئيسية، وخطوات إعادة الإنتاج، وستعرف كيف تستخدم نفس API الخاص بـ gpt-image-2 داخل البلاد دون الحاجة إلى تجاوز الحجب أو الانتظار، وذلك عبر قناة وكيل APIYI.

النقاط الجوهرية لـ openai-imagegen-demo

تفاصيل موقع مشروع imagegen-demo

يُعد openai-imagegen-demo في جوهره استوديو تصوير تفاعلي (Photobooth): حيث يقوم المستخدم برفع أو التقاط صورة شخصية، واختيار ما يصل إلى 4 أنماط محددة مسبقاً (مثل نمط الحياكة، الفن الرقمي، الرسم الزيتي، إلخ)، ليقوم التطبيق باستدعاء متزامن لنقطة نهاية images/edits الخاصة بـ gpt-image-2 عبر البث المباشر، مع إرجاع النتائج لكل نمط تدريجياً.

على عكس "عروض تحويل النص إلى صورة" الشائعة في السوق، يركز هذا المستودع الرسمي على قدرتين جديدتين: تحويل صورة إلى صورة (image editing) و المخرجات التدريجية المتدفقة (partial_images). الأولى تحل التحدي الهندسي المتمثل في "الحفاظ على اتساق الوجوه"، بينما تجعل الثانية تجربة الانتظار تتحول من شاشة سوداء لمدة 30 ثانية إلى ظهور تدريجي للإطارات.

شرح بنية مشروع imagegen-demo

تحليل الكود المصدري الرئيسي

يحتوي المشروع على مسار API واحد فقط وهو: app/api/photobooth/route.ts، وهو المسؤول عن حزم صورة البورتريه (الوجه) من الواجهة الأمامية مع "الموجه" (prompt) الخاص بالنمط، ثم إرسال طلب إلى نقطة النهاية /v1/images/edits الخاصة بـ OpenAI باستخدام نمط البث (Streaming). هيكل جسم الطلب الأساسي هو كما يلي:

const body = {
  model: "gpt-image-2",
  prompt: `${style.prompt}\n\n${OPENAI_IMAGE_OUTPUT_REQUIREMENTS}`,
  images: [{ image_url: imageDataUrl }],
  size: "1024x1536",
  quality: "high",
  output_format: "png",
  stream: true,
  partial_images: 2,
};

هناك ثلاث تفاصيل تستحق الاهتمام:

1. stream: true + partial_images: 2: هي قدرة بث حصرية لنموذج gpt-image-2؛ حيث يقوم الخادم بدفع إطارين وسيطين قبل تسليم الصورة النهائية.
2. معامل images: يستقبل رابط البيانات (data URL) لصورة مرجعية واحدة أو أكثر، مما يدعم تحرير ودمج صور متعددة.
3. OPENAI_IMAGE_OUTPUT_REQUIREMENTS: يفرض متطلبات مثل "نسبة أبعاد 2:3 للبورتريه، والحفاظ على وضعية الشخص وتعبيراته"، وهو النموذج الذهبي لكتابة "موجه" فعال لتحرير الصور.

تحليل أحداث البث

يقوم المسار (Route) بمراقبة استجابة OpenAI الرسمية عبر تقنية SSE (Server-Sent Events)، ويعالج الأنواع الثلاثة التالية من الأحداث:

• image_edit.partial_image: إطار وسيط، يقوم بدفع style-partial إلى الواجهة الأمامية.
• image_edit.completed: المنتج النهائي، يقوم بدفع style-final إلى الواجهة الأمامية.
• error: طرح استثناء، حيث تقوم الواجهة الأمامية بالتقاطه ومعالجته بشكل موحد.

في جانب React، تستخدم الواجهة الأمامية خطافًا (hook) مخصصًا للحفاظ على سلسلة writeQueue من نوع Promise، مما يضمن عدم تداخل ترتيب الأحداث عند وجود أنماط متعددة متزامنة، وهو الجزء الأكثر قيمة من الناحية الهندسية في هذا العرض التوضيحي.

البدء السريع مع imagegen-demo

خطوات التشغيل البسيطة

وفقًا لملف README الرسمي، يمكنك تشغيل المشروع بالكامل بـ 5 أوامر فقط:

git clone https://github.com/openai/openai-imagegen-demo
cd openai-imagegen-demo
cp .env.example .env.local
echo "OPENAI_API_KEY=sk-xxxxx" >> .env.local
npm install && npm run dev

# الخيار الأول: استخدام API الرسمي لـ OpenAI (يتطلب شبكة خارجية + حصة API)
OPENAI_API_KEY="sk-proj-xxxxx"

# الخيار الثاني: استخدام قناة التحويل لـ APIYI (اتصال مباشر محلي، بدون الحاجة لـ VPN)
OPENAI_API_KEY="your-apiyi-key"
OPENAI_BASE_URL="https://vip.apiyi.com/v1"

# اختياري: معرف المؤسسة والمشروع
OPENAI_ORG_ID=""
OPENAI_PROJECT_ID=""

const endpointBase = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";

const response = await fetch(`${endpointBase}/images/edits`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

نصيحة للربط: سيواجه المطورون في المناطق المحلية ثلاث عقبات رئيسية عند تشغيل العرض التوضيحي الرسمي لـ OpenAI (الشبكة، حصة API، وطرق الدفع). نوصي بالحصول على مفتاح متوافق عبر قناة التحويل الرسمية من APIYI (apiyi.com)، وتوجيه OPENAI_BASE_URL إلى https://vip.apiyi.com/v1 للبدء محلياً بضغطة زر واحدة، مع ضمان توافق أحداث البث والمعاملات تماماً مع النسخة الرسمية.

مقارنة حلول الربط لـ imagegen-demo

تحليل الحلول

تحليل الربط المباشر بـ OpenAI: تظل القناة الرسمية رائدة في الامتثال ومستوى الخدمة (SLA)، وهي البيئة الافتراضية المستهدفة لـ imagegen-demo. ومع ذلك، يتطلب التشغيل محلياً تجاوز قيود الشبكة، وامتلاك بطاقة ائتمان دولية، كما أن فترة مراجعة حصص الـ API طويلة. في المقابل، توفر قناة وكيل APIYI سهولة أكبر في الوصول وسرعة في التفعيل، مما يجعلها مثالية لمرحلة التحقق وبيئات الإنتاج المحلية.

تحليل fal Enterprise API: أطلقت fal في 21 أبريل 2026 نقطة نهاية مؤسسية لـ gpt-image-2، والتي تتميز بأداء عالٍ في التعامل مع الطلبات المتزامنة. لكن بالنسبة للمطورين المستقلين، فإن عتبة الدخول مرتفعة. بالنسبة للمطورين الذين يرغبون في تشغيل imagegen-demo محلياً، تعتبر APIYI خياراً أكثر مرونة وخفة.

الفرق بين قناة APIYI الرسمية (الوكيل) والقناة العكسية: قناة الوكيل تعني أن APIYI تقوم بتمرير طلباتك إلى API الرسمي الخاص بـ OpenAI، حيث تكون الفواتير، ومستوى الخدمة، والميزات مطابقة تماماً للرسمي، وهي مناسبة للسيناريوهات التجارية. أما القناة العكسية فهي تتحقق عبر عكس هندسة واجهة الويب لـ ChatGPT، وتوفر سعراً ثابتاً قدره $0.03 للصورة، مما يجعلها مثالية للنماذج الأولية. تتوفر كلتا القناتين بالتوازي على منصة APIYI، ويمكن للمطورين التبديل بينهما حسب الحاجة.

ملاحظة المقارنة: البيانات أعلاه مجمعة من تسعير OpenAI الرسمي، وإصدارات fal للمؤسسات، والوثائق التقنية لـ docs.apiyi.com؛ ويمكن التحقق منها عملياً عبر APIYI على apiyi.com.

شرح مفصل للمعلمات الرئيسية لـ gpt-image-2 (من كود المصدر لـ imagegen-demo)

بناءً على ملف lib/constants.ts في مشروع imagegen-demo، إليك مجموعات المعلمات الافتراضية الموصى بها رسمياً لنموذج gpt-image-2:

أفضل الممارسات لهندسة الموجه (Prompt Engineering)

يعد الثابت OPENAI_IMAGE_OUTPUT_REQUIREMENTS في العرض التوضيحي نموذجاً للموجه (prompt) ذا قيمة مرجعية عالية:

"portrait orientation (2:3 aspect ratio), preserve the exact people, poses, facial expressions, and scene composition as faithfully as possible"

تكشف هذه العبارة عن النموذج الذهبي لتحرير الصور باستخدام gpt-image-2:

• تحديد النسبة بوضوح: حتى لو قمت بضبط معلمة size، يجب إعادة ذكر النسبة في الموجه لزيادة دقة النتائج.
• التأكيد على متطلبات الدقة: عبارة preserve the exact ... هي "التعويذة" الأساسية للحفاظ على اتساق الوجوه.
• تعداد أبعاد الدقة: حدد بوضوح العناصر المراد الحفاظ عليها (الأشخاص، الوضعيات، تعابير الوجه، وتكوين المشهد)؛ فكلما كنت أكثر تحديداً، زادت دقة الاستعادة.

الأسئلة الشائعة (FAQ)

النقاط الجوهرية لـ openai-imagegen-demo

• مشروع مفتوح المصدر من OpenAI: عرض توضيحي رسمي مصاحب لـ gpt-image-2، مرخص بـ MIT للاستخدام التجاري.
• التركيز على "تحويل صورة إلى صورة": استخدام نقطة النهاية /v1/images/edits كنموذج هندسي للحفاظ على اتساق الوجوه.
• تقنية البث المباشر: استخدام stream: true + partial_images: 2 لتحويل الانتظار من شاشة سوداء إلى تصيير تدريجي.
• Next.js 15: بنية App Router + SSE هي الممارسة المثلى الحديثة لتطبيقات توليد الصور.
• طريق مختصر للربط: عبر APIYI (apiyi.com)، يكفي تعديل base_url واحد للاتصال المباشر.
• صيغة الموجه (Prompt) الذهبية: عبارة preserve the exact ... هي مفتاح الحفاظ على الدقة، وتستحق إضافتها لمشاريعك الخاصة.
• قنوات مزدوجة (رسمية وعكسية): اختر القناة الرسمية للأعمال (متوافقة مع OpenAI)، والقناة العكسية للتجارب (بسعر ثابت 0.03 دولار/صورة).

ملخص

يُعد openai-imagegen-demo أفضل نقطة انطلاق لفهم القدرات الجديدة لنموذج gpt-image-2، وتكمن قيمته الجوهرية في ثلاثة جوانب:

1. مرجع موثوق: نموذج تكامل رسمي من الشركة المطورة، يغطي المعلمات (Parameters)، الموجهات (Prompts)، وبنية التدفق (Streaming Architecture) بشكل كامل.
2. كود جاهز للإنتاج: يعتمد على Next.js 15 + SSE + التزامن متعدد الأنماط، مما يجعله قابلاً لإعادة الاستخدام مباشرة في مشاريعك الخاصة.
3. قابلية التشغيل محلياً: من خلال قناة وكيل APIYI، يمكن للمطورين تشغيل العرض التوضيحي الرسمي في غضون 5 دقائق فقط.

إذا كنت ترغب في تجربة قدرات تحرير الصور المتدفقة لنموذج gpt-image-2 على الفور، نوصي بالحصول على مفتاح API متوافق عبر منصة APIYI (apiyi.com)، ثم استنساخ openai-imagegen-demo وتوجيه OPENAI_BASE_URL إلى https://vip.apiyi.com/v1؛ وبذلك ستتمكن من محاكاة تأثير العرض التوضيحي الرسمي لـ OpenAI محلياً.

قراءات إضافية

إذا كنت مهتماً بـ gpt-image-2 و openai-imagegen-demo، نوصي بمتابعة القراءة حول المواضيع التالية:

• 📘 أين تجد واجهة برمجة تطبيقات (API) معكوسة لـ gpt-image-2؟ تعرف على قناة APIYI في 3 دقائق – اكتشف حلولاً منخفضة التكلفة بتكلفة 0.03 دولار للصورة الواحدة.
• 📊 مقارنة بين gpt-image-2 ونموذج Nano Banana Pro – تحليل للفروقات في قدرات نماذج الصور الرائدة.
• 🚀 دليل تطبيق gpt-image-2 في 6 قطاعات صناعية – استكشف حالات استخدام واقعية في التجارة الإلكترونية، التعليم، ووسائل التواصل الاجتماعي.

📚 المراجع

1. المستودع الرسمي لـ OpenAI imagegen-demo: الكود المصدري الكامل، ملف README، ووثائق التثبيت.

   • الرابط: github.com/openai/openai-imagegen-demo
   • الوصف: المصدر الأساسي للكود ودليل التثبيت، وهو نقطة البداية الموثوقة لفهم نمط دمج gpt-image-2.

2. وثائق OpenAI الرسمية لـ gpt-image-2 API: معلمات النموذج، نقاط النهاية (endpoints)، وتفاصيل الفوترة.

   • الرابط: developers.openai.com/api/docs/models/gpt-image-2
   • الوصف: للاطلاع على كافة المعلمات المدعومة، الأسعار، وقواعد تحديد معدل الاستخدام.

3. صفحة إطلاق OpenAI ChatGPT Images 2.0: مقدمة حول قدرات النموذج الجديد.

   • الرابط: openai.com/index/introducing-chatgpt-images-2-0/
   • الوصف: لفهم فلسفة تصميم gpt-image-2، قدراته الأساسية، وسيناريوهات الاستخدام.

4. وثائق خدمة وكيل APIYI لـ gpt-image-2: دليل الربط المباشر داخل الصين.

   • الرابط: docs.apiyi.com/en/api-capabilities/gpt-image-2-all/overview
   • الوصف: للحصول على مفتاح API متوافق، إعدادات base_url، وتفاصيل الأسعار.

المؤلف: الفريق التقني لـ APIYI
تبادل الخبرات: نرحب بمشاركتكم لتجاربكم العملية مع imagegen-demo في قسم التعليقات، وللمزيد من الوثائق يمكنكم زيارة مركز توثيق APIYI عبر الرابط docs.apiyi.com