Nano Banana 2 API

יכולות

תמחור וקרדיטים

Each image costs 4 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

אימות

צרו מפתח API בלוח הבקרה. המפתח המלא יוצג פעם אחת בלבד. שמרו אותו בשרת שלכם ושלחו אותו כטוקן Bearer בכל בקשה.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

הגדירו את משתנה הסביבה SEEVIO_API_KEY לפני הרצת דוגמאות אלו. דוגמאות ה-JavaScript רצות על השרת שלכם באמצעות Node.js; דוגמאות ה-Python משתמשות בחבילת requests.

גוף הבקשה

פרמטרי קלט

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

מדריך מהיר

שלחו בקשה בסיסית זו, שמרו את ה-taskId שמוחזר, והשתמשו בדוגמה לשאילתת משימה המופיעה להלן. ערך הקרדיטים (credits) בתגובת היצירה מייצג את כמות הקרדיטים השמורה עבור המשימה.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

דוגמה לתגובת יצירת משימה

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 4
}

מטקסט לתמונה

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

מתמונה לתמונה

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

החליפו את כתובות ה-URL לדוגמה של example.com בקובצי ה-HTTPS הציבוריים והנגישים שלכם. כתובות ה-URL שבדוגמה נועדו להמחיש את מבנה הבקשה בלבד ואינן זמינות להורדה.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

שאילתת משימה

החליפו את מזהה הדוגמה ב-taskId שהתקבל בעת היצירה. שאילתות יחזירו רק משימות השייכות למשתמש של מפתח ה-API; מזהים שאינם נגישים או שאינם קיימים יחזירו שגיאת HTTP 404.

כנקודת מוצא, בצעו שאילתה (polling) כל 10–20 שניות, הפחיתו את התדירות במקרה של שגיאת HTTP 429, ועצרו כאשר הסטטוס הופך ל-completed או failed. בסביבת פרודקשן מומלץ להשתמש ב-Webhooks. כל דוגמת קוד להלן מבצעת שאילתה אחת בלבד.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

בתור

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

הושלם

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

נכשל

כאשר השאילתה מחזירה status=failed, תהליך היצירה הסתיים ללא הצלחה. ניתן לראות את סיבת הכישלון ב-failed_reason ואת סטטוס ההחזר ב-billing_status. בדוגמה זו, refunded מציין שהקרדיטים הוחזרו. השדה credits שומר על הערך המקורי שהוזמן, והתגובה אינה כוללת את השדה data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

Webhooks

הגדירו callback_url בבקשת היצירה כדי לקבל בקשת POST מסוג JSON כאשר המשימה מסתיימת או נכשלת. החזירו תגובת 2xx בתוך 15 שניות. שליחות שנכשלו ינוסו שוב; טפלו בקבלת שידורים חוזרים בצורה אידמפוטנטית (idempotent) לפי מזהה המשימה.

קצה הקישור החוזר (callback endpoint) שלך חייב לקבל בקשות POST עם גוף בקשה מסוג JSON (Content-Type: application/json).

יצירת משימה עם קריאה חוזרת (Callback)

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

המשימה הושלמה: נתוני ה-payload של ה-callback שהצליח

השדה created_at מציין את זמן יצירת האירוע ו-task_created_at את זמן יצירת המשימה, בשניות Unix. הדוגמאות מציגות שדות מומלצים; התגובה עשויה לכלול שדות נוספים.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

המשימה נכשלה: נתוני ה-payload של ה-callback שנכשל

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 4
}

דוגמה לקוד קליטה (Receiver)

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

דוגמה זו ב-Next.js קוראת את גוף ה-JSON של ה-callback ומטפלת ישירות במשימות שהושלמו או נכשלו. מומלץ להוסיף שמירה בבסיס נתונים ומניעת כפילויות של מזהי משימות (task-ID deduplication) באפליקציה שלך; מומלץ להעביר עבודות איטיות לתור (queue) לפני החזרת אישור על קבלת ה-callback.

שגיאות

שגיאות HTTP מחזירות אובייקט error המכיל code (קוד) ו-message (הודעה). משימה שהתקבלה בהצלחה עדיין עלולה להיכשל בשלב מאוחר יותר; בצעו שאילתה על המשימה או טפלו בקריאה החוזרת של הכישלון שלה.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

מגבלות קצב בקשות

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

שאילתות משימות: כברירת מחדל, כל מפתח API מאפשר עד 120 בקשות בדקה. בקשות שאילתה ובקשות ליצירת משימות נספרות בנפרד.

Image and video creation requests share the same API key rate limit.

שגיאת HTTP 429 כוללת את הכותרת Retry-After: 60 עבור יצירה ו-Retry-After: 5 עבור שאילתות. השתמשו בהשהיית פניות (backoff) והימנעו מביצוע שאילתות בתדירות גבוהה מהנדרש.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}