GPT Image 2 API بلغة Python: مثال كامل

لاستخدام GPT Image 2 API من Python، أرسل طلبك بطريقة POST إلى https://api.seedrouter.ai/v1/images/generations باستخدام مكتبة requests، واحتفظ بمعرّف المهمة id الذي يُعاد إليك، واستعلم عن /v1/tasks/{id} حتى تصبح المهمة completed، ثم نزّل روابط الصور التي تسردها. ينفّذ السكربت أدناه الخطوات الأربع في نحو 40 سطرًا ويحفظ الصور على القرص.

يعمل كما هو بمجرد ضبط SEEDROUTER_API_KEY. وإذا لم يكن لديك مفتاح بعد، فاحصل على واحد أولًا.

كيف يبدو سكربت GPT Image 2 كامل؟

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    response = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
    return response.json()["id"]


def wait(task_id, limit_seconds=600):
    deadline = time.monotonic() + limit_seconds
    while time.monotonic() < deadline:
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return [image["url"] for image in task["output"]["data"]]
        if task["status"] == "failed":
            raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
        time.sleep(3)
    raise TimeoutError(f"Still running. Resume polling task {task_id}.")


def download(urls, prefix):
    paths = []
    for index, url in enumerate(urls):
        path = f"{prefix}-{index}.png"
        with open(path, "wb") as file:
            file.write(requests.get(url, timeout=60).content)
        paths.append(path)
    return paths


task_id = submit({
    "model": "gpt-image-2",
    "prompt": "A matte ceramic vase on a sunlit table, soft shadows",
    "size": "1024x1024",
    "quality": "low",
    "n": 2,
})
print("task", task_id)
print(download(wait(task_id), "vase"))

شغّله بالأمر python example.py. يطبع معرّف المهمة أولًا، ثم مسارَي ملفَّي PNG، هما vase-0.png وvase-1.png.

ماذا تفعل كل دالة؟

submit ترسل الطلب وتعيد معرّف المهمة. تحمل استجابة الخطأ دائمًا كائن error فيه code رقمي وmessage، لذا يخبرك الاستثناء بما يجب إصلاحه. فالرمز 400 مع الرمز 20001 والرسالة “Check the size parameter against the API documentation.”، مثلًا، يعني أن المقاس خالف إحدى القواعد في دليل المعاملات.

wait تستعلم كل ثلاث ثوانٍ حتى تنتهي المهمة. المهلة التي تضعها من جهتك توقف الحلقة لا المهمة: فعملية التوليد تستمر، ويمكنك استئناف الاستعلام عن المعرّف نفسه لاحقًا. والمهمة التي تنتهي بحالة failed ترفع استثناءً برمز خطئها ولا تُحتسب.

download تجلب كل رابط أعادته المهمة وتكتبه على القرص. روابط النتائج وسيلة تسليم لا تخزين دائم، لذا احفظ ما تريد الاحتفاظ به. يستخدم المثال requests للتنزيلات ولاستدعاءات API معًا؛ فالتزم بعميل HTTP واحد طوال الوقت بدلًا من خلطه بـ urllib من المكتبة القياسية.

كيف تغيّر إعدادات الصورة؟

كل شيء في جسم الطلب. الحقول التي يغيّرها معظم الناس أولًا:

إذا غيّرت output_format، فغيّر الامتداد .png في download ليطابقه. وتجد القائمة الكاملة للحقول والحدود في مرجع GPT Image 2 API.

كيف تحرّر صورة من Python؟

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

task_id = submit({
    "model": "gpt-image-2",
    "prompt": "Make the vase deep blue. Keep the table and the light unchanged.",
    "images": [{"image_url": "https://example.com/vase.png"}],
})

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

ماذا يفعل السكربت عند انتهاء مهلة الإرسال؟

لا تُعد الإرسال فورًا. انتهاء مهلة طلب POST لا يثبت أن الطلب رُفض؛ فقد تكون المهمة قيد التشغيل بالفعل وقد احتُسبت. تحقّق من مهامك الأخيرة، أو أعد محاولة الطلب فقط بعد التأكد من عدم إنشاء أي مهمة. ويشرح دليل المهام كيف تميّز بين الحالتين.

أما الاستعلام فمختلف: انتهاء المهلة أثناء الاستعلام لا ضرر منه. استدعِ wait مجددًا بالمعرّف نفسه.

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

هل يمكنني استخدام OpenAI Python SDK بدلًا من ذلك؟

ليس مباشرة. تسلّم هذه الـ API النتائج بشكل غير متزامن عبر معرّف مهمة، بينما يتوقع استدعاء الصور في الـ SDK أن تكون الصورة الجاهزة داخل الاستجابة. وبضعة أسطر من requests، كما في الأعلى، تغطي المسار كله.

كيف أشغّل عدة موجّهات؟

أرسل كل موجّه، واحفظ كل معرّفات المهام، ثم استعلم عنها. ويعرض دليل الدفعات نسخة تصمد أمام إعادة التشغيل دون أن تدفع مرتين.

هل يحتاج gpt-image-2-official إلى شفرة مختلفة؟

لا. غيّر سلسلة model ولا شيء غيرها. يقبل المعرّفان الحقول نفسها ويعيدان استجابة المهمة نفسها؛ ولا يختلف سوى الاحتساب.

احتفظ بمعرّف المهمة، والباقي مجرد توصيلات

أرسل، واحفظ المعرّف، واستعلم مع مهلة، ونزّل ما يعود إليك. هذا النمط هو التكامل كله. وجرّب موجّهًا دون شفرة في Playground الخاص بـ GPT Image 2 قبل أن تكتب له سكربتًا.