Nano Banana 2.1 API

Funktionen

Preise & Credits

Jede Anfrage erzeugt ein Bild. Die Credits richten sich nach der unten angegebenen Auflösung. Sie werden bei Annahme reserviert, bei Erfolg abgerechnet und bei Fehlschlag erstattet.

Idempotenz von Anfragen wird nicht unterstützt. Jeder gültige POST-Request erstellt einen neuen, kostenpflichtigen Task. Wenn das Ergebnis einer Übermittlung unklar ist, fragen Sie die zurückgegebene taskId ab. Ein erneuter POST-Request kann einen weiteren Task erstellen.

Authentifizierung

Erstellen Sie einen API-Key im Dashboard. Der vollständige Key wird nur einmal angezeigt. Speichern Sie ihn auf Ihrem Server und senden Sie ihn bei jeder Anfrage als Bearer-Token mit.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Setzen Sie die Umgebungsvariable SEEVIO_API_KEY, bevor Sie diese Beispiele ausführen. JavaScript-Beispiele laufen mit Node.js auf Ihrem Server; Python-Beispiele nutzen das requests-Paket.

Request-Body

Eingabeparameter

Das Seitenverhältnis (aspect ratio) ist standardmäßig auf „auto“ eingestellt. Jede Anfrage generiert genau ein Bild.

Schnellstart

Senden Sie diese minimale Anfrage, speichern Sie die zurückgegebene taskId und nutzen Sie das untenstehende Beispiel zur Task-Abfrage. Der Credits-Wert in der Erstellungsantwort entspricht dem reservierten Betrag.

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-1",
  "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"
  }
}'

Beispiel für die Antwort beim Erstellen eines Tasks

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

Text zu Bild

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-1",
  "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"
  }
}'

Bild zu Bild

Setzen Sie für die Bildbearbeitung generation_type auf image-to-image und geben Sie image_urls an. Für alle anderen Parameter gilt dieselbe Struktur.

Ersetzen Sie die Medien-URLs von example.com durch Ihre eigenen, öffentlich zugänglichen HTTPS-Dateien. Die Beispiel-URLs dienen nur zur Veranschaulichung der Request-Struktur und sind keine herunterladbaren Beispieldateien.

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-1",
  "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"
    ]
  }
}'

Task abfragen

Ersetzen Sie die Beispiel-ID durch die bei der Erstellung zurückgegebene taskId. Abfragen liefern nur Tasks zurück, die dem User des API-Keys gehören; bei unzugänglichen oder unbekannten IDs wird HTTP 404 zurückgegeben.

Fragen Sie anfangs alle 10–20 Sekunden ab, drosseln Sie die Frequenz bei HTTP 429 und stoppen Sie, sobald der Status completed oder failed lautet. Nutzen Sie für die Produktion bevorzugt Webhooks. Jedes Codebeispiel unten führt eine einzelne Abfrage aus.

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

In der Warteschlange

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

Abgeschlossen

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": null,
  "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
  }
}

Fehlgeschlagen

Wenn die Abfrage status=failed zurückgibt, wurde die Generierung erfolglos beendet. Unter failed_reason finden Sie die Ursache und unter billing_status das Erstattungsergebnis. In diesem Beispiel bedeutet refunded, dass die Credits zurückerstattet wurden. credits behält den ursprünglich reservierten Betrag bei, und die Antwort enthält keine data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Ergebnis-Links werden nach der Speicherung 30 Tage lang bereitgestellt. Nach Ablauf dieser Frist bleibt das Feld results leer.

Webhooks

Setzen Sie callback_url in der Erstellungsanfrage, um einen JSON-POST zu erhalten, sobald der Task abgeschlossen ist oder fehlschlägt. Antworten Sie innerhalb von 15 Sekunden mit einem 2xx-Statuscode. Fehlgeschlagene Zustellungen werden wiederholt; verarbeiten Sie doppelte Zustellungen idempotent anhand der Task-ID.

Ihr Callback-Endpunkt muss POST-Anfragen mit einem JSON-Body (Content-Type: application/json) akzeptieren.

Task mit Callback erstellen

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-1",
  "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 nutzen die Struktur der Task-Abfrageantwort. Benachrichtigungen über erstattete Fehler enthalten zusätzlich das Top-Level-Feld credits_refunded. Verwenden Sie id zur Identifizierung des Tasks und status, um zwischen erfolgreich abgeschlossen und fehlgeschlagen zu unterscheiden. Benachrichtigungen können mehrfach gesendet werden: Verarbeiten Sie diese idempotent nach id und status. Callbacks sind nicht signiert. Verifizieren Sie den Task über den authentifizierten Abfrage-Endpunkt. Ein Fehlschlagen der Zustellung führt nicht zur Erstattung eines erfolgreichen Tasks.

Task abgeschlossen: Payload für erfolgreichen Callback

created_at ist die Ereigniszeit, task_created_at die Erstellungszeit der Aufgabe, jeweils in Unix-Sekunden. Die Beispiele zeigen empfohlene Felder; Antworten können weitere Felder enthalten.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": null,
  "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
}

Task fehlgeschlagen: Payload für fehlgeschlagenen Callback

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 3
}

Empfänger-Beispiel

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 });
}

Dieses Next.js-Beispiel liest den JSON-Callback-Body aus und verarbeitet erfolgreiche sowie fehlgeschlagene Tasks direkt. Fügen Sie für Ihre eigene Anwendung Datenpersistenz und Task-ID-Deduplizierung hinzu. Stellen Sie zeitaufwendige Prozesse in eine Warteschlange, bevor Sie den Callback bestätigen.

Fehler

HTTP-Fehler enthalten ein error-Objekt mit code und message. Auch ein erfolgreich angenommener Task kann später noch fehlschlagen; fragen Sie den Task ab oder verarbeiten Sie den Callback für Fehler.

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

Fehler verwenden error.code und error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Der Fehler 402 insufficient_credits bedeutet, dass Ihr verfügbares Guthaben für diese Anfrage nicht ausreicht.

Rate Limits

Tasks erstellen: Pro API-Schlüssel sind standardmäßig bis zu 100 Anfragen pro Minute zulässig. Individuelle Ratenbegrenzungen sind derzeit nicht verfügbar.

Tasks abfragen: Pro API-Schlüssel sind standardmäßig bis zu 120 Anfragen pro Minute zulässig. Abfragen und Erstellungsanfragen werden separat gezählt.

Anfragen zur Bild- und Videoerstellung teilen sich das gleiche Ratenlimit des API-Keys.

HTTP 429 enthält Retry-After: 60 bei der Erstellung und Retry-After: 5 bei Abfragen. Nutzen Sie Backoff-Verfahren und vermeiden Sie unnötig häufiges Polling.

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

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