Nano Banana Pro (Gemini 3 Pro Image)

יצירת תמונות ועריכתן עם Nano Banana Pro דרך נקודת קצה אסינכרונית אחת, עם גוף generateContent של Google: חשיבה מובנית, פלט 4K ו-14 ייחוסים.

Nano Banana Pro (ננו בננה פרו) הוא מודל Gemini 3 Pro Image של Google, שנבנה לנכסים מקצועיים ולהוראות מורכבות. הוא חושב לפני שהוא מצייר, ולכן התגובות מדווחות על טוקני חשיבה. שלח את גוף הבקשה generateContent של Google עם שדה model, שמור את מזהה המשימה שהוחזר, ותשאל את המשימה כדי לקבל את התמונה המוכנה. תמונות ייחוס נכנסות ל-contents ככתובות fileData.

מזהי מודל

מזהה מודל	ערוץ	אופן החיוב
`gemini-3-pro-image`	Standard	מחיר קבוע לכל תמונה שנמסרה
`gemini-3-pro-image-official`	Official	תעריפים לפי טוקנים לקלט, לפלט טקסט/חשיבה ולפלט תמונה

שני המזהים מקבלים את אותם פרמטרים. המחירים הנוכחיים מופיעים בדף המודל.

דוגמה מהירה

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

נקודת קצה

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

כותרת	ערך
Authorization	`Bearer YOUR_API_KEY`
Content-Type	`application/json`

הגוף הוא בקשת generateContent של Google עם תוספת אחת: model, כי בנתיב של נקודת הקצה הזאת אין שם מודל. התגובה מכילה מזהה משימה, לא את התמונה המוכנה. שמור את מפתחות ה-API בקוד צד השרת. קריאה ישירה ל-/v1beta/models/...:generateContent אינה נתמכת; השתמש בנקודת הקצה הזאת.

פרמטרים

שם	סוג	חובה	ברירת מחדל	הערות
`model`	string	כן	—	אחד משני מזהי המודל שלמעלה.
`contents`	Content[]	כן	—	1–32 תורות. לכל אחת `parts` ו-`role` אופציונלי (`user` או `model`); התור האחרון הוא `user`.
`contents[].parts[].text`	string	—	—	חלק טקסט. נדרש לפחות חלק טקסט אחד.
`contents[].parts[].fileData`	object	לא	—	`{"mimeType": "...", "fileUri": "https://..."}`; תמונת ייחוס. עד 14 בסך הכול.
`systemInstruction`	object	לא	—	`{"parts": [{"text": "..."}]}`.
`safetySettings`	object[]	לא	—	זוגות `{"category", "threshold"}`; ראה למטה.
`generationConfig.responseModalities`	enum[]	לא	טקסט ותמונה	`["IMAGE"]` לתמונות בלבד, או `["TEXT", "IMAGE"]`.
`generationConfig.imageConfig.aspectRatio`	enum	לא	היחס של תמונת הקלט, אחרת `1:1`	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
`generationConfig.imageConfig.imageSize`	enum	לא	`1K`	`1K`, `2K`, `4K`. האות `K` גדולה.
`generationConfig.candidateCount`	integer	לא	`1`	רק `1`. בקשה אחת מחזירה תמונה אחת.
`generationConfig.temperature`	number	לא	ברירת המחדל של המודל	0–2.
`generationConfig.topP`	number	לא	ברירת המחדל של המודל	0–1.
`generationConfig.topK`	integer	לא	ברירת המחדל של המודל	1 ומעלה.
`generationConfig.seed`	integer	לא	—	מספר שלם של 32 ביט.
`generationConfig.maxOutputTokens`	integer	לא	ברירת המחדל של המודל	1–32,768.
`generationConfig.stopSequences`	string[]	לא	—	עד 5.
`generationConfig.mediaResolution`	enum	לא	ברירת המחדל של המודל	`MEDIA_RESOLUTION_LOW`, `MEDIA_RESOLUTION_MEDIUM`, `MEDIA_RESOLUTION_HIGH`. קובע כמה טוקנים צורכת מדיית הקלט.
`generationConfig.thinkingConfig.includeThoughts`	boolean	לא	`false`	מחזיר את סיכומי החשיבה של המודל ב-`output.thoughts`.
`generationConfig.responseFormat.image`	object	לא	—	`mimeType`: `IMAGE_JPEG`; `delivery`: `INLINE`; `aspectRatio` ו-`imageSize` כערכי enum של Google, למשל `ASPECT_RATIO_SIXTEEN_BY_NINE` ו-`IMAGE_SIZE_TWO_K`, עם אותם יחסי גובה-רוחב וגדלים כמו ב-`imageConfig`. `gemini-3-pro-image-official` אינו מקבל שדה זה.

קטגוריות בטיחות: HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT. ספים: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE, OFF.

שדות לא מוכרים נדחים. עדיין לא זמינים: עיגון בחיפוש Google (tools) ותוכן שמור במטמון; thinkingLevel אינו מתועד עבור המודל הזה. inlineData אינו מתקבל; העבר מדיה ככתובות fileData. responseFormat.image.delivery מקבל רק INLINE: תמונות מוכנות מוחזרות תמיד ככתובות מאוחסנות.

גודל הפלט

`imageSize`	פלט ביחס 1:1	טוקני תמונה
`1K`	1024×1024	1,120
`2K`	2048×2048	1,120
`4K`	4096×4096	2,000

יחסי גובה-רוחב אחרים שומרים על אותו מספר טוקנים; למשל 16:9 ב-1K הוא 1376×768.

מצבים

אין פרמטר מצב נפרד ואין נקודת קצה נפרדת לעריכה.

פעולה	פרמטרים
טקסט לתמונה	חלק טקסט
עריכה או הרכבה	חלק טקסט + חלק `fileData` אחד או יותר
עריכה בכמה תורות	תורות `user` ו-`model` קודמות, ואחריהן תור `user` חדש (ראה את ההערה למטה)

כדי להמשיך שיחה, בנה מחדש את תור ה-model מתוך output.parts של המשימה הקודמת, לפי הסדר: חלק טקסט הופך ל-{"text": ..., "thoughtSignature": ...} וחלק תמונה הופך ל-{"fileData": {"mimeType": "image/<output_format>", "fileUri": <data[image].url>}, "thoughtSignature": ...}. שמור כל thoughtSignature בדיוק כפי שהוחזר: זו כתובת ה-URL של החתימה ששמרנו עבורך (החתימה של תמונת 4K שוקלת כמה מגה-בייט), ואנחנו משחזרים אותה לפני שהבקשה מגיעה למודל. מתקבלות רק חתימות מתוצאות המשימות שלך.

עריכה עם תמונת ייחוס

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

החלף את כתובת הדוגמה בתמונה נגישה משלך.

קלט מדיה

ה-API הזה מקבל הפניות לכתובות URL בלבד. inlineData ב-Base64, כתובות data: והעלאות multipart אינם מתקבלים. ה-Playground מעלה את הקבצים שנבחרו לאחסון לפני שהוא שולח את הכתובות שלהם.

תמונות ייחוס חייבות להיות כתובות HTTP(S) ציבוריות של קובצי PNG, JPEG, WebP, HEIC או HEIF, כל אחת קטנה מ-50 MB ובסך הכול פחות מ-100 MB. mimeType חייב להתאים לקובץ. הכתובות נטענות במהלך העיבוד; תמונה שאינה נגישה גורמת לכישלון המשימה, ומשימה שנכשלה אינה מחויבת.

גורמי עלות

בדוק את מדור המחירים של המודל לתעריפים הנוכחיים. gemini-3-pro-image מחייב מחיר קבוע לכל תמונה שנמסרה, בלי קשר לגודל או לפרומפט. gemini-3-pro-image-official מחייב לפי שימוש: טוקני קלט (טקסט ותמונות ייחוס), טוקני פלט של טקסט וחשיבה, וטוקני פלט של תמונה, כל אחד בתעריף משלו. גודל התמונה הוא הגורם העיקרי; ראה את הטבלה שלמעלה.

את החיובים הסופיים תראה בהיסטוריית השימוש של החשבון שלך. משימות שנכשלו אינן מחויבות.

מבנה הפלט

השליחה מחזירה הפניה למשימה:

{
  "id": "task_...",
  "model": "gemini-3-pro-image",
  "status": "processing",
  "created_at": 1790310979
}

תשאול המשימה

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

תשאל כל כמה שניות עד ש-status יהיה completed או failed. פקיעת זמן ברשת במהלך התשאול אינה מעידה שהיצירה נכשלה: שמור את מזהה המשימה והמשך לבדוק אותה. אל תיצור משימה נוספת כדי לבדוק התקדמות.

דוגמת תשאול מלאה

הרץ זאת אחרי דוגמת השליחה ב-Python שלמעלה.

import time

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": "gemini-3-pro-image",
  "status": "completed",
  "created_at": 1790310979,
  "finished_at": 1790311001,
  "output": {
    "created": 1790310999,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.jpg"}],
    "output_format": "jpeg",
    "usage": {
      "input_tokens": 27,
      "output_tokens": 1366,
      "total_tokens": 1393,
      "output_tokens_details": {"image_tokens": 1120, "text_tokens": 95, "reasoning_tokens": 151}
    }
  }
}

שדה	משמעות
`id`	שמור את המזהה הזה לתשאולים הבאים.
`status`	`processing`, `completed` או `failed`.
`created_at`, `finished_at`	חותמות זמן Unix בשניות.
`output.data[].url`	כתובת התמונה שנוצרה.
`output.text`	טקסט שהמודל החזיר לצד התמונה, כש-`responseModalities` כולל `TEXT`. החשיבה אינה נכללת.
`output.thoughts`	סיכומי החשיבה של המודל, כש-`includeThoughts` הוא `true`. תמונות ביניים שהמודל מצייר בזמן החשיבה אינן נמסרות.
`output.output_format`	פורמט התמונה בפועל.
`output.parts`	חלקי התגובה הסופיים לפי הסדר, לעריכה בכמה תורות: `{"text", "thoughtSignature"}` או `{"image": <index into data>, "thoughtSignature"}`. `thoughtSignature` הוא כתובת URL; שלח אותו בחזרה ללא שינוי.
`output.usage`	שימוש בטוקנים. `output_tokens` סופר פלט של טקסט, חשיבה ותמונה; `output_tokens_details.image_tokens` הוא החלק של התמונה.
`error`	שגיאה מובנית במשימה שנכשלה.

סטרימינג (streamGenerateContent) אינו נתמך; התוצאות נמסרות דרך המשימה.

שגיאות

בקשות שנדחות לפני יצירת המשימה מחזירות שגיאת HTTP יחד עם אובייקט error. משימה שנכשלת לאחר שהתקבלה מחזירה בתשאול HTTP 200, עם status: "failed" ואובייקט error. תמונה שנחסמה על ידי מסנני הבטיחות של המודל נכשלת עם content_policy_violation; תגובה ללא תמונה נכשלת עם no_output.

ראה את קטלוג השגיאות המשותף לקודים, לסטטוסי HTTP ולהנחיות ניסיון חוזר.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

אם השליחה עצמה חורגת מהזמן הקצוב, בדוק את היסטוריית המשימות לפני שליחה חוזרת: ייתכן שהבקשה הראשונה כבר התקבלה.

טיפים

תאר את הנושא, הסביבה, התאורה והסגנון במשפטים מלאים.
בעריכה, ציין מה צריך להשתנות ומה חייב להישאר כפי שהוא.
2K צורך אותם טוקני תמונה כמו 1K; השתמש ב-4K לנכסים בגודל הדפסה.
שמור את התמונות שהוחזרו באחסון שלך אם אתה צריך עותק קבוע.