GPT Image 2.5 API بلغة Python: مثال عملي يعمل

لاستدعاء GPT Image 2.5 API، أرسل طلب POST إلى https://api.seedrouter.ai/v1/images/generations مع معرّف نموذج مثل gpt-image-2.5-flare وموجّه، واحتفظ بقيمة id الخاصة بالمهمة من الاستجابة، ثم استعلم عبر GET /v1/tasks/{id} حتى تصبح الحالة completed. وتحتوي المهمة المكتملة على روابط صورك. وتتعامل نقطة النهاية نفسها مع تحويل النص إلى صورة، والتحرير بالصور المرجعية، والتحرير بقناع.

يقدّم هذا الدليل مسارًا كاملًا قابلًا للتشغيل بلغة Python، مع ما يقابله في JavaScript، ثم الأخطاء الأكثر شيوعًا ومعنى كل منها.

ما الذي تحتاجه قبل الطلب الأول؟

أمران: مفتاح API ومعرّف نموذج.

أنشئ مفتاحًا في صفحة مفاتيح API واحفظه في متغير بيئة على خادمك، لا في شفرة المتصفح أبدًا:

export SEEDROUTER_API_KEY="your-key"

ثم اختر أحد معرّفات نموذج GPT Image 2.5 الأربعة. انسخها كما هي تمامًا؛ فلا يوجد معرّف gpt-image-2.5 مجرّد.

إذا لم تكن متأكدًا من النموذج الذي تبدأ به، فاستخدم Flare؛ ويشرح Flare أم Sunburst متى يستحق Sunburst.

كيف تولّد صورة باستخدام Python؟

يعود الإرسال فورًا. والاستجابة مرجع لمهمة، لا الصورة.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

احفظ 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}.")

نزّل الروابط التي تريد الاحتفاظ بها وخزّنها بنفسك. فروابط النتائج وسيلة تسليم، لا تخزين طويل الأمد.

كيف يبدو الاستدعاء نفسه بلغة JavaScript؟

الطلب مطابق؛ ولا يتغيّر سوى عميل HTTP. شغّله على خادمك حتى لا يصل المفتاح إلى المتصفح أبدًا.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

استعلم عبر GET https://api.seedrouter.ai/v1/tasks/${taskId} بالترويسة نفسها، تمامًا كما في حلقة Python.

كيف تحرّر صورة موجودة؟

أضف صورًا مرجعية إلى الطلب نفسه. لا توجد نقطة نهاية منفصلة للتحرير ولا حقل للوضع: فإرسال images يجعله تحريرًا، وإضافة mask تقصر التغيير على منطقة واحدة.

{
  "model": "gpt-image-2.5-sunburst",
  "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"}
}

يجب أن تكون المدخلات روابط HTTPS عامة. يمكنك إرسال حتى 16 صورة مرجعية بصيغة PNG أو JPEG أو WebP، حجم كل منها أقل من 50 ميغابايت. والقناع صورة PNG أقل من 4 ميغابايت، بمقاس الصورة المرجعية الأولى نفسه، وتحدّد منطقته الشفافة ما يجب تغييره. وتُرفض سلاسل base64 وروابط data: ورفع الملفات، لذا ارفع الملفات إلى تخزينك الخاص أولًا وأرسل الروابط.

لماذا تقول API إن النموذج غير متاح؟

يعني رمز الخطأ 20002 مع HTTP 400 (“The requested model is not available.”) أن قيمة model ليست معرّفًا تقدّمه API. والسبب المعتاد خطأ قريب من الصواب: gpt-image-2.5 دون مستوى، أو gpt-image-2-5-flare بشرطة بدل النقطة، أو خطأ إملائي في sunburst. انسخ معرّفًا من الجدول أعلاه.

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

وقد تفشل المهمة أيضًا بعد قبولها. ويظل هذا الاستعلام يعيد HTTP 200، مع status: "failed" وكائن error مثل الرمز 60001 (سياسة المحتوى) أو 60002 (فشل التوليد). والمهام الفاشلة لا تُحتسب. ويسرد دليل الأخطاء كل رمز، بما في ذلك أخطاء الرصيد وحدود المعدل، مع الخطوة التالية لكل منها.

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

هل يوجد استدعاء رسمي في Python SDK يعيد الصورة مباشرة؟

ليس على هذه API. فالتسليم غير متزامن: ترسل دائمًا، وتحتفظ بمعرّف المهمة، ثم تستعلم. ولا يُدعم stream ولا partial_images.

هل يمكنني طلب عدة صور دفعة واحدة؟

نعم. اضبط n من 1 إلى 10. تسرد المهمة المكتملة رابطًا واحدًا لكل صورة تُسلَّم، ويُحتسب عليك ما سُلِّم من صور.

كيف أحصل على صورة PNG شفافة؟

اضبط background على transparent وoutput_format على png. فصيغة JPEG لا تحتوي على قناة ألفا، لذا تُرفض هذه التركيبة قبل تشغيلها.

ابنِ التكامل حول معرّف المهمة

خزّن معرّف المهمة لحظة استلامه، واستعلم ضمن مهلة محددة، وتعامل مع انتهاء مهلة الاستعلام على أنه "ما زال قيد التنفيذ" لا "فشل". وكل ما عدا ذلك، بما فيه كل حقل وكل حد، موجود في مرجع GPT Image 2.5 API، ويمكنك تجربة طلب دون شفرة في Playground.