دليل عملي من 9 خطوات لدمج gpt-image-2 مع مفتاح API الرسمي: من الصفر إلى الإنتاج

أصبح نموذج gpt-image-2 الذي أطلقته OpenAI في أبريل 2026 النموذج الأكثر إثارة للاهتمام في مجال توليد الصور، حيث يتميز بدقة عرض نصي على مستوى الحروف تصل إلى 99%، وإخراج بدقة 4K، ودعم أصلي للغة الصينية/CJK، بالإضافة إلى دمج قدرات الاستدلال من سلسلة O. ومع ذلك، فإن السؤال الأول الذي يطرحه العديد من المطورين عند الحصول على النموذج هو: كيف يمكن ربط gpt-image-2 بـ API الرسمي؟ ما هي المعلمات المطلوبة؟ كيف يتم ضبط base_url؟ وكيف نتعامل مع b64_json في الاستجابة؟

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

قائمة التحقق للبدء في دمج gpt-image-2 مع واجهة برمجة التطبيقات (API) الرسمية

قبل كتابة السطر الأول من الكود، يجب عليك تجهيز البيئة المناسبة. تغطي القائمة التالية المتطلبات الأربعة الأساسية لدمج gpt-image-2 مع واجهة برمجة التطبيقات الرسمية.

قائمة متطلبات بيئة العمل لدمج gpt-image-2

عنصر التحضير	المتطلبات	ملاحظات
مفتاح API	Bearer Token صالح	يُطلب عبر لوحة تحكم APIYI، ويمكن الحصول على رصيد تجريبي فور التسجيل
Python SDK	`openai >= 1.50.0`	الإصدارات القديمة لا تدعم المعاملات الجديدة لـ `images.generate()`
Node.js SDK	`openai >= 4.50.0`	أنواع TypeScript متوافقة مع الإصدار الرسمي
مهلة HTTP	≥ 360 ثانية	تستغرق جودة high + دقة 2K/4K ما بين 3-5 دقائق فعلياً
متطلبات الشبكة	اتصال مباشر محلي	يمكن الوصول إلى `api.apiyi.com` من الشبكات المحلية أو المنزلية أو الدولية

تثبيت SDK لدمج gpt-image-2

بغض النظر عن لغة البرمجة التي تختارها، ما عليك سوى تثبيت OpenAI SDK الرسمي؛ حيث تتطابق قنوات التحويل في APIYI تماماً مع الحقول الرسمية، ولا حاجة لمكتبات عميل إضافية.

# Python
pip install --upgrade openai

# Node.js
npm install openai@latest

# إذا كنت تستخدم yarn / pnpm
yarn add openai
pnpm add openai

خطوات الحصول على مفتاح API لدمج gpt-image-2

خطوات الحصول على مفتاح API بسيطة للغاية:

قم بزيارة لوحة تحكم APIYI عبر api.apiyi.com
بعد تسجيل الحساب، ادخل إلى صفحة "رموز API" (API Tokens)
أنشئ رمزاً جديداً (يُفضل استخدام رمز مستقل لكل مشروع لتسهيل المراجعة)
احفظ الرمز في متغيرات البيئة (لا يُنصح بشدة بترميزه داخل الكود)

🚀 نصيحة للبدء السريع: عند دمج gpt-image-2 لأول مرة، نوصي بالبدء بجودة منخفضة + دقة 1024×1024 لاختبار المسار، ثم الانتقال إلى جودة high والأحجام الكبيرة. نقترح الحصول على رصيد تجريبي عبر منصة APIYI، حيث يكفي الرصيد المجاني لإتمام عملية التحقق الكاملة (PoC).

# أضف هذا إلى ملف ~/.zshrc أو ~/.bashrc
export APIYI_KEY="sk-your-token-here"

إعداد base_url لدمج gpt-image-2

في عملية دمج gpt-image-2 بأكملها، الشيء الوحيد المختلف عن OpenAI SDK الأصلي هو base_url. قم باستبدال api.openai.com بـ api.apiyi.com، وستظل بقية الأكواد متطابقة تماماً.

نقطتا النهاية لدمج gpt-image-2

توفر APIYI نقطتي نهاية للصور متطابقتين تماماً مع OpenAI:

نقطة النهاية	الاستخدام	المعاملات المطلوبة
`POST /v1/images/generations`	تحويل النص إلى صورة (توليد عبر موجه)	`model`، `prompt`
`POST /v1/images/edits`	تحرير الصور، دمج الصور، إعادة الرسم باستخدام القناع	`model`، `prompt`، `image`

تهيئة العميل لدمج gpt-image-2

فيما يلي كود تهيئة العميل للغتي Python و Node.js، وتذكر دائماً ضبط المهلة الزمنية على 360 ثانية أو أكثر.

# Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",  # الانتقال إلى قناة التحويل APIYI
    timeout=600.0,                         # ضروري لتمديد المهلة في سيناريوهات الجودة العالية
    max_retries=2
)

// Node.js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIYI_KEY,
  baseURL: "https://api.apiyi.com/v1",  // لاحظ أن الاسم هو baseURL (بصيغة camelCase)
  timeout: 600 * 1000,                  // بالملي ثانية
  maxRetries: 2
});

💡 تذكير بضبط المهلة: المهلة الافتراضية (60 ثانية) ستؤدي حتماً إلى فشل الطلبات في سيناريوهات الجودة العالية (high) ودقة 2K/4K. نوصي عند الدمج عبر APIYI بضبط مهلة الطلب لجميع عملاء بيئة الإنتاج بين 360 و600 ثانية لتجنب انقطاع الطلبات الطويلة بشكل خاطئ.

ننتقل الآن إلى الجانب العملي. فيما يلي استعراض لكيفية إجراء أول عملية تحويل نص إلى صورة باستخدام gpt-image-2 عبر واجهة برمجة التطبيقات (API) الرسمية باستخدام ثلاث لغات برمجة.

تحويل النص إلى صورة باستخدام Python و gpt-image-2

import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",
    timeout=600.0
)

response = client.images.generate(
    model="gpt-image-2",
    prompt="A modern minimalist office desk with a vintage typewriter, soft morning light from the window, photorealistic, 8K",
    size="1536x1024",
    quality="high",
    output_format="jpeg",
    output_compression=92,
    n=1
)

# نقطة هامة: APIYI تعيد سلسلة base64 خام، بدون بادئة data:image/...
b64 = response.data[0].b64_json
with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(b64))

print("✓ تم حفظ الصورة في output.jpg")

تحويل النص إلى صورة باستخدام Node.js و gpt-image-2

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

const client = new OpenAI({
  apiKey: process.env.APIYI_KEY,
  baseURL: "https://api.apiyi.com/v1",
  timeout: 600_000
});

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt: "An e-commerce product photo of a leather backpack on a marble desk, studio lighting",
  size: "1024x1024",
  quality: "high",
  output_format: "png",
  n: 1
});

const b64 = response.data[0].b64_json;
await fs.writeFile("output.png", Buffer.from(b64, "base64"));
console.log("✓ تم حفظ الصورة");

تحويل النص إلى صورة باستخدام cURL و gpt-image-2

تعد أداة cURL مثالية للتحقق السريع من صلاحية مفتاح API واختبار مجموعات المعلمات الجديدة.

curl https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer $APIYI_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic cyberpunk city at night, neon signs in mixed Chinese and English",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "jpeg",
    "output_compression": 90,
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 -d > output.jpg

ملاحظة: تأكد من إضافة --max-time 600؛ حيث أن cURL لا يمتلك مهلة زمنية افتراضية، لكن العديد من بيئات shell تفرض انقطاعاً تلقائياً بعد 60 ثانية.

نقاط أساسية عند معالجة استجابة API لـ gpt-image-2

يواجه العديد من المطورين صعوبة في تحليل base64 عند الاتصال لأول مرة. إليك أخطاء شائعة يجب تجنبها:

# ✗ خطأ: APIYI لا تعيد حقل url
url = response.data[0].url  # AttributeError

# ✓ صحيح: استخدم b64_json
b64 = response.data[0].b64_json

# ✗ خطأ: المتصفح لا يعرض سلسلة b64 الخام مباشرة
<img src="{b64}">  # لن تظهر الصورة

# ✓ صحيح: يجب إضافة البادئة يدوياً لعرضها في المتصفح
data_uri = f"data:image/jpeg;base64,{b64}"
# <img src="{{ data_uri }}">

# ✓ صحيح: الحفظ على القرص في جانب الخادم
with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(b64))

شرح كامل لمعلمات gpt-image-2 عبر API

يعد فهم نطاق القيم والحالات المناسبة لكل معلمة أمراً حاسماً عند نقل استخدام gpt-image-2 إلى بيئة الإنتاج.

جدول المعلمات الأساسية لـ gpt-image-2 عبر API

المعلمة	القيمة	القيمة الافتراضية	الوصف
`model`	`"gpt-image-2"`	مطلوب	معرف النموذج
`prompt`	نص	مطلوب	الموجه، يدعم العربية والإنجليزية
`size`	8 خيارات مسبقة + مخصص	`auto`	انظر الجدول أدناه
`quality`	`auto` / `low` / `medium` / `high`	`auto`	تؤثر على التكلفة والوقت
`output_format`	`png` / `jpeg` / `webp`	`png`	نوصي بـ jpeg + ضغط 90
`output_compression`	1-100	100	تؤثر فقط على jpeg/webp
`moderation`	`auto` / `low`	`auto`	low تقلل حساسية المراجعة
`n`	1-10	1	عدد الصور في الطلب الواحد

خيارات حجم الصورة (size) لـ gpt-image-2

# 8 خيارات رسمية مسبقة
size = "1024x1024"   # 1:1 مربع قياسي
size = "1536x1024"   # 3:2 أفقي
size = "1024x1536"   # 2:3 عمودي
size = "2048x2048"   # 2K مربع
size = "2048x1152"   # 16:9 أفقي (مناسب لخلفيات الحاسوب/الملصقات)
size = "3840x2160"   # 4K أفقي
size = "2160x3840"   # 4K عمودي (مناسب لخلفيات الهاتف)
size = "auto"        # اختيار تلقائي بواسطة النموذج

إذا كنت بحاجة إلى أبعاد مخصصة، يجب استيفاء القيود التالية:

✓ طول الضلع يجب أن يكون مضاعفاً للرقم 16
✓ أقصى طول للضلع ≤ 3840 بكسل
✓ نسبة الطول إلى العرض ≤ 3:1
✓ إجمالي عدد البكسلات بين 655,360 و 8,294,400

على سبيل المثال، 1280x720 (720P) مقبول، بينما 3840x1080 (شاشة عريضة جداً) سيتم رفضه لأن النسبة أكبر من 3:1.

مقارنة الجودة والتكلفة لـ gpt-image-2

تعد معلمة quality الأكثر تأثيراً على التكلفة. إليك جدول الأسعار الكامل (لكل صورة).

الجودة	1024×1024	1024×1536	1536×1024	حالات الاستخدام
`low`	$0.006	$0.005	$0.005	مسودات، صور مصغرة، تجارب سريعة
`medium`	$0.053	$0.041	$0.041	مواقع المحتوى، صور المقالات
`high`	$0.211	$0.165	$0.165	صور المنتجات، ملصقات، إعلانات

💰 تحسين التكلفة: بالنسبة لفرق المحتوى التي تولد 100 صورة يومياً، يساهم استخدام جودة medium بدلاً من high في توفير 75% من التكاليف. ننصح باستخدام منصة APIYI (apiyi.com) لتجربة الموجه (prompt) بجودة low أولاً، ثم الترقية إلى medium/high عند اعتماد النتيجة النهائية، مما قد يقلل ميزانية توليد الصور الشهرية بنسبة 30-50%.

اختيار صيغة المخرجات (output_format)

تؤثر صيغة الملف بشكل مباشر على تكاليف التخزين وسرعة التحميل:

# هل تحتاج خلفية شفافة؟ gpt-image-2 لا يدعم ذلك، وسيعيد خطأ 400
# ✗ output_format="png", background="transparent" → 400 Bad Request

# للعرض على الويب/التطبيقات: jpeg + ضغط 90
output_format="jpeg", output_compression=90

# للأرشفة عالية الدقة: png (بدون فقدان للجودة)
output_format="png"

# لتطبيقات الويب الحديثة: webp هو الأقل حجماً
output_format="webp", output_compression=85

بالإضافة إلى تحويل النص إلى صورة، يدعم gpt-image-2 ثلاثة سيناريوهات تحرير متقدمة: تحرير الصور، دمج صور متعددة، والتحرير الموضعي (Inpainting/Outpainting).

تحرير الصور عبر API الرسمي لـ gpt-image-2 (وضع الصورة المرجعية)

يتم تفعيل وضع "الدقة العالية" (high-fidelity) تلقائياً عند استخدام الصور المرجعية، لذا لا تقم بتمرير معامل input_fidelity (سيتم رفض الطلب).

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1"
)

# تحرير صورة مرجعية واحدة
with open("source.jpg", "rb") as img:
    response = client.images.edit(
        model="gpt-image-2",
        image=img,
        prompt="استبدل الخلفية بشاطئ عند الغروب، مع الحفاظ على وضعية الشخصية والملابس في المقدمة",
        size="1024x1024",
        quality="high"
    )

دمج صور متعددة عبر API الرسمي لـ gpt-image-2 (حتى 16 صورة)

يدعم نقطة النهاية /images/edits إدخال ما يصل إلى 16 صورة مرجعية في وقت واحد، ويمكنك الإشارة إليها في الموجه (prompt) باستخدام "الصورة 1/الصورة 2/الصورة 3".

images = [
    open("character.jpg", "rb"),     # الصورة 1: الشخصية
    open("background.jpg", "rb"),    # الصورة 2: الخلفية
    open("outfit.jpg", "rb"),        # الصورة 3: مرجع الملابس
]

response = client.images.edit(
    model="gpt-image-2",
    image=images,
    prompt="ضع الشخصية من الصورة 1 في خلفية الصورة 2، واجعلها ترتدي نمط ملابس الصورة 3، مع الحفاظ على الجودة السينمائية",
    size="2048x1152",
    quality="high"
)

تعتبر هذه القدرة قوية للغاية في سيناريوهات مثل تغيير خلفيات المنتجات للتجارة الإلكترونية، تجربة الملابس الافتراضية، وتوليد لوحات القصص المصورة (مانغا).

التحرير الموضعي (Inpainting) عبر API الرسمي لـ gpt-image-2

يتم تحديد المنطقة المراد إعادة رسمها عبر معامل mask. القواعد الأساسية:

يجب أن يكون القناع (mask) بنفس أبعاد الصورة المرجعية الأولى.
يجب أن يكون القناع بصيغة PNG مع قناة ألفا (alpha channel).
المناطق الشفافة = المناطق المراد إعادة رسمها.
المناطق غير الشفافة = المناطق التي سيتم الاحتفاظ بها من الصورة الأصلية.

with open("photo.png", "rb") as img, open("mask.png", "rb") as msk:
    response = client.images.edit(
        model="gpt-image-2",
        image=img,
        mask=msk,
        prompt="استبدل المنطقة المحددة بالإطار الأحمر بقطة برتقالية",
        size="1024x1024",
        quality="high"
    )

إذا كنت بحاجة إلى توليد القناع برمجياً في بايثون، يمكنك استخدام مكتبة PIL:

from PIL import Image

# إنشاء قناع بنفس أبعاد الصورة الأصلية، افتراضياً أسود بالكامل (غير شفاف = احتفاظ)
mask = Image.new("RGBA", (1024, 1024), (0, 0, 0, 255))

# تحويل المنطقة المراد إعادة رسمها إلى شفافة (alpha=0)
for x in range(400, 700):
    for y in range(300, 600):
        mask.putpixel((x, y), (0, 0, 0, 0))

mask.save("mask.png")

التعامل مع الأخطاء والممارسات الإنتاجية عند ربط gpt-image-2 بـ API الرسمي

عند نقل نموذج gpt-image-2 إلى بيئة الإنتاج، يجب عليك التعامل بجدية مع ثلاثة جوانب رئيسية: رموز الخطأ، التزامن (Concurrency)، والمهلة الزمنية (Timeout).

جدول رموز الخطأ الكامل عند ربط gpt-image-2 بـ API الرسمي

رمز حالة HTTP	المعنى	الإجراء الموصى به
`400`	معاملات غير صالحة (تجاوز حجم الصورة، إرسال حقول غير مدعومة)	تحقق من المدخلات؛ لا ترسل `input_fidelity` أو `background:transparent`
`401`	رمز مميز (Token) غير صالح	تحقق من Bearer Token وتأكد من عدم انتهاء صلاحيته
`403`	حظر بسبب مراجعة المحتوى	عدّل الموجه (Prompt)، أو أضف `moderation: "low"`
`429`	تجاوز حد الطلبات / رصيد غير كافٍ	استخدم التراجع الأسي (Exponential Backoff) مع فحص الرصيد
`5xx`	خطأ في البوابة أو الخادم	أعد المحاولة 1-2 مرة، وإذا استمر الفشل، أرسل تنبيهاً
مهلة زمنية	تأخر في استجابة الطلبات الطويلة	اضبط مهلة العميل (Client Timeout) لتكون ≥ 360 ثانية

التراجع الأسي (Exponential Backoff) عند ربط gpt-image-2 بـ API الرسمي

فيما يلي نموذج برمجي جاهز للإنتاج للتعامل مع أخطاء 429 و 5xx:

import time
import random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",
    timeout=600.0
)

def generate_with_retry(prompt: str, max_retries: int = 5):
    delay = 1.0
    for attempt in range(max_retries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high"
            )
        except RateLimitError:
            sleep = delay + random.uniform(0, 0.5)
            print(f"خطأ 429: تجاوز الحد، إعادة المحاولة بعد {sleep:.1f} ثانية ({attempt+1}/{max_retries})")
            time.sleep(sleep)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < max_retries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("تم تجاوز الحد الأقصى لعدد المحاولات")

التحكم في التزامن عند ربط gpt-image-2 بـ API الرسمي

للمهام الجماعية، استخدم asyncio.Semaphore لتقييد عدد الطلبات المتزامنة وتجنب إغراق الخادم:

import asyncio
from openai import AsyncOpenAI

aclient = AsyncOpenAI(
    api_key=os.getenv("APIYI_KEY"),
    base_url="https://api.apiyi.com/v1",
    timeout=600.0
)

async def gen_one(prompt: str, sem: asyncio.Semaphore):
    async with sem:
        return await aclient.images.generate(
            model="gpt-image-2",
            prompt=prompt,
            size="1024x1024",
            quality="medium"
        )

async def batch(prompts: list[str], concurrency: int = 30):
    sem = asyncio.Semaphore(concurrency)
    return await asyncio.gather(*[gen_one(p, sem) for p in prompts])

# تنفيذ 200 صورة بـ 30 طلب متزامن
prompts = [f"نموذج صورة منتج #{i}" for i in range(200)]
results = asyncio.run(batch(prompts))

تقدير التكاليف عند ربط gpt-image-2 بـ API الرسمي

قبل الإطلاق، قم بتقدير التكاليف. إليك تقديرات شهرية لسيناريوهات نموذجية:

سيناريو العمل	الحجم اليومي	الجودة	التكلفة الشهرية التقديرية
صور وسائط اجتماعية	30 صورة	medium	~$48
صور منتجات تجارة إلكترونية	200 صورة	high	~$1266
توليد صور لمستخدمي SaaS	1000 مرة	medium	~$1590
إطارات رئيسية للألعاب	500 صورة	high	~$3165

🎯 نصيحة للنشر: نوصي بطلب مفتاح API منفصل لكل خط عمل لتسهيل تتبع التكاليف وعزل حدود الاستخدام. نقترح تفعيل تنبيهات الفواتير عبر لوحة تحكم APIYI (apiyi.com) لتلقي إشعارات عند الوصول إلى حد معين وتجنب تجاوز الميزانية.

المراقبة (Observability) عند ربط gpt-image-2 بـ API الرسمي

في بيئة الإنتاج، تأكد من تسجيل المؤشرات الرئيسية لكل طلب:

import time
import logging

logger = logging.getLogger("gpt-image-2")

def call_with_metrics(prompt: str, **params):
    start = time.perf_counter()
    try:
        resp = client.images.generate(model="gpt-image-2", prompt=prompt, **params)
        latency = time.perf_counter() - start
        logger.info(
            "نجاح استدعاء gpt-image-2",
            extra={
                "latency_ms": int(latency * 1000),
                "size": params.get("size"),
                "quality": params.get("quality"),
                "n": params.get("n", 1)
            }
        )
        return resp
    except Exception as e:
        logger.error(f"فشل استدعاء gpt-image-2: {type(e).__name__}: {e}")
        raise

الأسئلة الشائعة حول ربط gpt-image-2 بـ API الرسمي

س1: لماذا يظهر خطأ 400 عند استخدام `input_fidelity`؟

نموذج gpt-image-2 يقوم بتفعيل high-fidelity تلقائياً في جميع سيناريوهات التعديل، لذا يتم رفض معامل input_fidelity. قم بحذفه ببساطة. إذا كنت ترحل من gpt-image-1 إلى gpt-image-2 ابحث عن هذا المعامل في كودك واحذفه. نوصي بمقارنة اختلافات المعاملات عبر وثائق APIYI: docs.apiyi.com.

س2: لماذا تنتهي مهلة استدعاءات `gpt-image-2` غالباً؟

تستغرق الصور عالية الجودة بدقة 2K/4K ما بين 3 إلى 5 دقائق. إذا كانت المهلة الافتراضية للعميل 60 ثانية، فسيحدث فشل حتمي. الحل: اضبط timeout على 360-600 ثانية.

س3: كيف أعرض `b64_json` العائد من API على صفحة الويب؟

يعيد API سلسلة base64 خام بدون بادئة، لذا لا يمكن للمتصفح عرضها مباشرة. يجب دمجها:

const dataUri = `data:image/${format};base64,${b64}`;
imgElement.src = dataUri;

إذا كنت تستخدم خدمة خلفية (Backend)، يُفضل فك تشفير base64 وحفظ الصورة في OSS/CDN، ثم إرسال الرابط فقط للمتصفح.

س4: هل يدعم `gpt-image-2` الخلفية الشفافة؟

حالياً لا يدعم ذلك، وإرسال background: "transparent" سيؤدي لخطأ 400. الحل البديل: توليد صورة بخلفية بيضاء/خضراء ثم استخدام مكتبة مثل rembg لإزالة الخلفية برمجياً.

س5: كيف أستخدم معامل `thinking`؟

thinking هو معامل استنتاج (قيم: off / low / medium / high). تفعيل هذا المعامل يجعل النموذج يخطط للتكوين قبل التوليد، مما يرفع الجودة لكن بتكلفة أعلى. نصيحة: استخدم medium فقط في الملصقات المعقدة، واتركه off في السيناريوهات العادية.

س6: ماذا أفعل عند مواجهة خطأ 403 (مراجعة المحتوى)؟

حاول إضافة moderation: "low" في الطلب لتقليل الحساسية. إذا استمر الحظر، فهذا يعني أن الموجه ينتهك سياسات الأمان الأساسية (مثل العنف أو صور الشخصيات العامة)، ويجب إعادة صياغة الموجه.

س7: ماذا يحدث إذا كان `base_url` خاطئاً؟

إذا كتبت https://api.apiyi.com (بدون /v1)، سيقوم SDK بتركيب الرابط بشكل خاطئ مما يؤدي لخطأ 404. الصيغة الصحيحة هي https://api.apiyi.com/v1.

س8: ما هي أفضل الممارسات لدمج صور متعددة؟

يمكنك استخدام ما يصل إلى 16 صورة مرجعية. نصيحة:

الصورة المرجعية الأولى تُعتبر "الأساس" الذي يحافظ النموذج على هيكله.
للتعليمات المعقدة، قسّم الطلب: "استخدم الصورة 1 كجسم رئيسي، وادمج ألوان الصورة 2".
تكلفة تعديل الصور المتعددة أعلى بـ 1.5-2 مرة من توليد النص إلى صورة.

ملخص: مراجعة المسار الكامل لربط gpt-image-2 بـ API الرسمي

بعد الانتهاء من الفصول التسعة في هذا الدليل، يجب أن تكون قد أتقنت المنهجية الهندسية الكاملة لـ ربط gpt-image-2 بـ API الرسمي:

✅ التحضير —— تحديث حزمة SDK إلى أحدث إصدار، وضبط مهلة الانتظار (timeout) لتكون ≥ 360 ثانية.
✅ إعداد base_url —— استبداله بـ https://api.apiyi.com/v1، مع بقاء باقي الكود متوافقاً تماماً مع النسخة الرسمية.
✅ استدعاء تحويل النص إلى صورة —— قوالب برمجية بثلاث لغات: Python وNode.js وcURL.
✅ شرح المعاملات —— 8 إعدادات مسبقة للحجم (size) + تخصيص، 3 مستويات للجودة (quality)، و3 خيارات لتنسيق المخرجات (output_format).
✅ تعديل الصور —— دعم ما يصل إلى 16 صورة مرجعية، واستخدام "صورة 1/صورة 2" في الموجه (prompt) للإشارة إليها.
✅ إعادة الرسم (Inpainting) —— استخدام قناة ألفا (alpha channel) للقناع (mask) لإعادة رسم المناطق الشفافة.
✅ معالجة الأخطاء —— حلول شاملة لأكواد الخطأ 400/401/403/429/5xx.
✅ الممارسات الإنتاجية —— التراجع الأسي (exponential backoff)، التحكم في التزامن، تقدير التكلفة، والمراقبة.

نصيحة أخيرة للتنفيذ: ابدأ بتشغيل تجربة "Hello World" باستخدام جودة low ودقة 1024×1024، ثم زد التعقيد تدريجياً. يساعدك هذا في اكتشاف المشكلات الأساسية المتعلقة بإصدار SDK، أو مهلة الانتظار، أو مفتاح API بسرعة، وتجنب إضاعة وقت التصحيح في طلبات معقدة بدقة 4K وجودة عالية.

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

المراجع

وثائق نموذج OpenAI gpt-image-2: شرح موثوق لقدرات النموذج، المعاملات، والتسعير.
- الرابط: developers.openai.com/api/docs/models/gpt-image-2
- ملاحظة: يتضمن ميزات أساسية مثل العرض بدقة 4K، النصوص على مستوى الأحرف، وتكامل الاستدلال.
دليل توليد الصور من OpenAI: سير عمل كامل لتحويل النص إلى صورة، التعديل، وإعادة الرسم (inpainting).
- الرابط: developers.openai.com/api/docs/guides/image-generation
- ملاحظة: يغطي شرحاً مفصلاً لجميع معاملات الحجم والجودة والتنسيق.
مرجع API لإنشاء الصور من OpenAI: الحقول الكاملة لنقطة النهاية /v1/images/generations.
- الرابط: developers.openai.com/api/reference/resources/images/methods/generate
- ملاحظة: مرجع موثوق لحقول الطلب والاستجابة.
وثائق الربط الرسمية لـ APIYI: دليل الربط الكامل لنموذج gpt-image-2 باللغة العربية.
- الرابط: docs.apiyi.com/api-capabilities/gpt-image-2/overview
- ملاحظة: يحتوي على أمثلة cURL/Python/Node.js ومعالجة أكواد الخطأ.
كتاب وصفات OpenAI · حدود المعدل (Rate Limits): حل التراجع الأسي لأخطاء 429.
- الرابط: developers.openai.com/cookbook/examples/how_to_handle_rate_limits
- ملاحظة: قالب كود رسمي موصى به للتعامل مع قيود المعدل.

المؤلف: فريق APIYI التقني
تاريخ النشر: 27 أبريل 2026
الكلمات المفتاحية: ربط gpt-image-2 بـ API الرسمي، base_url، تحويل النص إلى صورة، تعديل الصور، إعادة الرسم (inpainting)، APIYI، OpenAI SDK