GPT Image 2.5

يقبل GPT Image 2.5 نصًا توجيهيًا وصورًا مرجعية اختيارية. أرسل الطلب مرة واحدة، واحتفظ بمعرّف المهمة المُعاد، ثم استعلم عن تلك المهمة للحصول على الصور المكتملة. ويأتي في نموذجين يقرآن المعاملات نفسها: Flare للعمل اليومي، وSunburst عندما تكون دقة التحرير هي الأهم.

معرّفات النموذج

تقبل المعرّفات الأربعة المعاملات نفسها. وتختلف القناتان في طريقة الاحتساب؛ راجع صفحة النموذج للاطلاع على الأسعار الحالية.

مثال سريع

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

نقطة النهاية

POST https://api.seedrouter.ai/v1/images/generations

تتولى نقطة النهاية نفسها الإنشاء والتحرير بالمراجع والتحرير بالقناع. وتحتوي الاستجابة على معرّف مهمة لا على الصورة المكتملة. واحتفظ بمفاتيح API في شفرة تعمل على الخادم.

المعاملات

قواعد الحجم

الخيارات الشائعة هي 1024x1024 و1536x1024 و1024x1536. ويجب أن تستوفي الأبعاد المخصصة القواعد كافة:

• أن يكون العرض والارتفاع من مضاعفات 16.
• ألا يتجاوز أي ضلع 3840 بكسل.
• أن تكون نسبة العرض إلى الارتفاع بين 1:3 و3:1.
• أن تكون المساحة الكلية بين 655,360 و8,294,400 بكسل، شاملة الطرفين.

تترك auto تحديد أبعاد المخرجات للنموذج. ولا ترسل نسب أبعاد مثل 16:9 في الحقل size.

يوفر Playground أدوات التحكم Auto والنسبة والمخصص. ويجمع وضع النسبة بين نسبة الأبعاد وإعداد جاهز لميزانية البكسل بمقدار 1K أو 2K أو 4K، ثم يرسل قيمة size الناتجة فقط. وهذه إعدادات في الواجهة لا معاملات مستقلة في الواجهة البرمجية: فلا ترسل resolution ولا aspect_ratio. فمثلًا يرسل 16:9 + 4K القيمة size: "3840x2160"؛ ويرسل 9:16 + 4K القيمة "2160x3840"؛ ويرسل 1:1 + 2K القيمة "2048x2048". وقد يقلل التقريب وحد الضلع عدد البكسلات للمستوى المختار. وتظهر الأبعاد الدقيقة قبل الإرسال.

تصف OpenAI الدقات التي تتجاوز 2560×1440 بأنها تجريبية. وهي مقبولة ضمن الحدود أعلاه؛ غير أن الدقة الأعلى لا تضمن تفاصيل أفضل.

مستويات الجودة

xhigh وmax درجتان جديدتان في GPT Image 2.5؛ إذ يتوقف GPT Image 2 عند high. وتستغرق الدرجات الأعلى وقتًا أطول في التوليد، وتستهلك على المعرّفات المحتسبة بالتوكنات توكنات مخرجات أكثر. وعند القياس بمقاس 1024x1024، أبلغت عملية توليد واحدة عن 196 و439 و1,756 و3,122 و7,024 توكن مخرجات للدرجات low وmedium وhigh وxhigh وmax على التوالي. وهذه عيّنات مرصودة لا ضمانات: فالاستهلاك يعتمد أيضًا على المقاس والمحتوى.

استخدم low للمسودات وقارن النتائج قبل اختيار مستوى أعلى. وتترك auto الاختيار للنموذج؛ وهي لا تضمن مستوى بعينه ولا تكلفة بعينها.

الخلفيات الشفافة

خاصية الشفافية مدعومة في GPT Image 2.5. وللحصول على خلفية شفافة اضبط background: "transparent" واستخدم PNG. ولا يدعم JPEG الشفافية. ولا ينطبق الضغط إلا على JPEG.

الحقل user متاح لعمليات التكامل عبر الواجهة البرمجية، لكنه لا يظهر في Playground ولا يُملأ تلقائيًا فيه.

تقبل الإعدادات القياسية الاختيارية (n وsize وquality وbackground وoutput_format وoutput_compression وmoderation) القيمة null للدلالة على الإغفال. وتُرفض الحقول غير المعروفة. وinput_fidelity ليس من معاملات GPT Image 2.5. أما style وresponse_format فتخصّان نماذج صور أخرى ولا تُقبلان هنا.

الأوضاع

لا يوجد معامل مستقل للوضع ولا نقطة نهاية منفصلة للتحرير تختار بينها.

تحرير الصور المرجعية

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Make the bottle blue. Preserve the composition and lighting.",
    "images": [{"image_url": "https://example.com/reference.png"}],
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

استبدل رابطَي المثال بصورك أنت بحيث يمكن الوصول إليها. واحذف mask إذا أردت تحريرًا بصورة مرجعية دون تحديد منطقة بعينها.

مدخلات الوسائط

لا تقبل هذه الواجهة سوى الإشارة عبر الروابط. ولا تُقبل معرّفات OpenAI Files ولا روابط data بصيغة base64 ولا الرفع بصيغة multipart. ويرفع Playground الملفات المختارة إلى التخزين أولًا ثم يرسل روابطها.

يجب أن تكون الصور المرجعية روابط HTTP(S) عامة تشير إلى ملفات PNG أو JPEG أو WebP بحجم أقل من 50 ميغابايت لكل ملف. ويجب أن يكون القناع ملف PNG بحجم أقل من 4 ميغابايت وبالأبعاد نفسها للصورة المرجعية الأولى؛ وتحدّد منطقته الشفافة ما سيجري تحريره. والقناع يوجّه النموذج ولا يضمن حدودًا دقيقة على مستوى البكسل. وعند وجود عدة مراجع ينطبق القناع على الصورة الأولى. ويجري التحقق من الوسائط المشار إليها بالروابط أثناء المعالجة؛ وقد تؤدي الوسائط غير الصالحة أو التي يتعذّر الوصول إليها إلى فشل المهمة.

يرفع Playground الملفات المختارة ويرسل روابطها. وتستخدم طلبات الواجهة البرمجية كائنات روابط بصيغة JSON: فلا ترسل بايتات الملفات ولا base64 ولا روابط data: ولا روابط blob: ولا بيانات نماذج multipart.

عوامل التكلفة

راجع قسم أسعار النموذج للاطلاع على الأسعار الحالية. تحتسب معرّفات Standard سعرًا ثابتًا لكل صورة تُسلَّم، بصرف النظر عن الجودة والمقاس والموجّه. أما على معرّفات Official فتعتمد التكلفة النهائية على استهلاك المدخلات والمخرجات، ويؤثّر فيها كلٌّ من الجودة وأبعاد المخرجات والصور المرجعية وطول الموجّه وعدد الصور.

يستند التقدير في Playground إلى عيّنة مقيسة وإلى الأسعار الحالية؛ وهو ليس عرض سعر مضمونًا. راجع الرسوم النهائية في سجل الاستخدام الخاص بحسابك. ولا تُحتسب رسوم على المهام الفاشلة.

بنية المخرجات

يعيد الإرسال مرجعًا للمهمة:

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "processing",
  "created_at": 1789970508
}

الاستعلام عن المهمة

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

استعلم على فترات معتدلة، كل ثلاث ثوانٍ مثلًا، حتى تصبح قيمة status هي completed أو failed. وانتهاء مهلة الشبكة أثناء الاستعلام لا يعني فشل الإنشاء: احتفظ بمعرّف المهمة واستأنف التحقق. ولا تنشئ مهمة أخرى لمعرفة التقدّم.

مثال استعلام كامل

شغّل هذا بعد مثال الإرسال بلغة Python الوارد أعلاه. يستخدم المثال task_id المُعاد وينتظر حتى عشر دقائق. وبلوغ هذه المهلة المحلية يوقف الاستعلام فحسب؛ احتفظ بالمعرّف واستأنف الاستعلام عن المهمة نفسها.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

المهمة المكتملة

تعيد المهمة المكتملة روابط الصور المستضافة وبيانات الاستخدام:

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

تسلّم هذه الواجهة النتائج عبر مهام غير متزامنة. وهي ليست بديلًا عن Images SDK المتزامن؛ ولا تدعم stream ولا partial_images.

الأخطاء

الطلبات المرفوضة قبل إنشاء المهمة تعيد خطأ HTTP مصحوبًا بكائن error. أما المهمة التي تفشل بعد قبولها فتعيد عند الاستعلام رمز HTTP 200 مع status: "failed" وكائن error.

راجع كتالوج الأخطاء المشترك للاطلاع على الرموز وحالات HTTP وإرشادات إعادة المحاولة. وتستخدم جميع واجهات النماذج البنية نفسها للأخطاء.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

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

نصائح

• صف الخامات والتكوين والإضاءة في النص التوجيهي.
• عند التحرير، حدّد التغيير المطلوب وما ينبغي أن يبقى دون تغيير معًا.
• استخدم قناعًا عندما يقتصر التغيير على منطقة محددة.
• احفظ الصور المُعادة في تخزينك الخاص إذا احتجت إلى نسخة دائمة.

مواضيع ذات صلة

• Playground وأسعار GPT Image 2.5
• تنزيل OpenAPI
• Markdown قابل للنسخ