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. המשימה שהסתיימה מכילה כתובות URL לתמונות שלך. אותה נקודת קצה מטפלת ביצירה מטקסט לתמונה, בעריכות לפי תמונות ייחוס ובעריכות עם מסכה.

המדריך הזה הוא מסלול מלא שאפשר להריץ ב-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 MB. המסכה היא PNG מתחת ל-4 MB, באותו גודל כמו תמונת הייחוס הראשונה, והאזור השקוף שלה מסמן מה לשנות. מחרוזות 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 אין ערוץ אלפא, ולכן השילוב הזה נדחה לפני שהוא רץ.

בנה את האינטגרציה סביב מזהה המשימה

שמור את מזהה המשימה ברגע שאתה מקבל אותו, תשאל עם מועד אחרון, והתייחס לפקיעת זמן בתשאול כאל "עדיין רץ" ולא "נכשל". כל השאר, כולל כל שדה וכל מגבלה, נמצא בתיעוד ה-API של GPT Image 2.5, ואפשר לנסות בקשה בלי קוד ב-Playground.