Jak używać Nano Banana 2 API: klucz, żądanie i wynik

Aby używać Nano Banana 2 API, utwórz klucz API, wyślij treść żądania generateContent Google z polem model na jeden punkt końcowy i odpytuj zwrócone zadanie, aż adres URL obrazu będzie gotowy. Te same kroki działają dla Nano Banana Pro i Nano Banana 2 Lite; zmienia się tylko wartość model.

Ten poradnik przeprowadza cię przez każdy krok z działającym kodem, a potem pokazuje, jak edytować z obrazami referencyjnymi i jak przekazać zadanie agentowi AI do programowania.

Czego potrzebujesz przed pierwszym żądaniem?

1. Klucza API. Utwórz go na stronie kluczy API i trzymaj na swoim serwerze. Nigdy nie umieszczaj go w kodzie przeglądarki.
2. Kredytów. Doładuj saldo na stronie rozliczeń. Kredyty nigdy nie wygasają, a nieudane żądania nie są rozliczane.
3. ID modelu. gemini-3.1-flash-image nalicza stałą cenę za obraz; gemini-3.1-flash-image-official rozlicza tokeny. Wybrać pomoże ci przewodnik po cenach.

export SEEDROUTER_API_KEY="your-key"

Jak wysłać żądanie do Nano Banana 2?

Wyślij żądanie POST na /v1/images/generations. Treść ma kształt generateContent Google z dodanym polem model:

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

Odpowiedzią jest zadanie, a nie obraz:

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

Jeśli już wywołujesz API Google, wysyłasz tę samą treść, którą wysłałbyś do generateContent. Bezpośrednie wywołanie /v1beta/models/...:generateContent w SeedRouter nie jest obsługiwane; używaj tego punktu końcowego.

Jak odebrać obraz?

Odpytuj zadanie co kilka sekund, aż status będzie completed lub failed. W Pythonie:

import os
import time
import requests

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

response = requests.post(
    f"{API}/images/generations",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image",
        "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(f"{API}/tasks/{task_id}", headers=headers, 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}.")

Zakończone zadanie ma adres URL obrazu w output.data[0].url, a także zużycie tokenów. Przy "responseModalities": ["TEXT", "IMAGE"] tekst napisany przez model wraca w output.text. Jeśli potrzebujesz obrazu na dłużej, pobierz go do własnego magazynu.

Przekroczenie limitu czasu podczas odpytywania nie oznacza, że obraz się nie udał. Zachowaj identyfikator zadania i sprawdź je ponownie; wysłanie nowego żądania oznacza zapłatę za drugi obraz.

Jak edytować obraz lub użyć referencji?

Dodaj części fileData obok tekstu. Każda z nich to publiczny adres URL i jego typ MIME:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-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"}}
      ]
    }]
  }'

Nano Banana 2 przyjmuje do 14 referencji na żądanie: obrazy, filmy lub pliki PDF, każdy poniżej 50 MB. Referencje muszą być adresami URL; base64 inlineData nie jest akceptowane. Jeśli adresu URL nie da się pobrać, zadanie kończy się niepowodzeniem i nie jest rozliczane. Przy kolejnej edycji wyślij wcześniejsze tury jako wpisy user i model i zakończ nową turą user.

Które ustawienia są najważniejsze?

Dokumentacja Nano Banana 2 API wymienia każde pole i limit. Nieznane pola są odrzucane, zanim cokolwiek zostanie naliczone, a grounding z wyszukiwarką Google (tools) nie jest jeszcze dostępny.

Jak pozwolić agentowi AI korzystać z Nano Banana 2 API?

Agent AI do programowania, taki jak Claude Code, Codex czy Cursor, może wywołać API poleceniem powłoki lub krótkim skryptem. SeedRouter nie udostępnia serwera MCP ani gotowego skilla; ten prompt to cała integracja. Najpierw wyeksportuj klucz, a potem wklej:

Use the SeedRouter API to generate a Nano Banana 2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, setting, style, what the image is for]
Size: [512 | 1K | 2K | 4K]    Aspect ratio: [e.g. 1:1, 16:9, 9:16]
References: [public image URLs, or none]

Send POST https://api.seedrouter.ai/v1/images/generations with
{"model": "gemini-3.1-flash-image",
 "contents": [{"parts": [{"text": "..."}, {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://..."}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
   "imageConfig": {"aspectRatio": "...", "imageSize": "..."}}}
Accepted top-level fields: model, contents, systemInstruction, safetySettings,
generationConfig. References must be fileData URLs (up to 14), never base64.
Do not add tools or any other field.

Before sending, show me the request body and wait for my approval: each
request is charged. Then poll GET https://api.seedrouter.ai/v1/tasks/{id}
every 3 seconds until status is completed or failed. If polling times out,
keep checking the same task; never resubmit. Save output.data[0].url into
./images/ and tell me the file path.

Krok zatwierdzenia jest ważny: agent wydaje twoje saldo, więc nigdy nie powinien wysyłać żądań sam z siebie.

Najczęściej zadawane pytania

Jak uzyskać klucz API do Nano Banana 2?

Zaloguj się, otwórz stronę kluczy API i utwórz klucz. Ten sam klucz działa dla Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite i pozostałych modeli w SeedRouter.

Czy Nano Banana 2 API obsługuje żądania wsadowe?

Wysyłaj jedno żądanie na obraz i odpytuj zadania równolegle. Każde żądanie zwraca jeden obraz, a każde zadanie jest rozliczane osobno.

Jakie błędy powinienem obsłużyć?

Kod 400 oznacza, że treść naruszyła regułę, na przykład zawiera nieznane pole lub nieobsługiwany rozmiar, i nic nie jest naliczane. Zadanie zakończone jako failed zawiera komunikat o błędzie i również nie jest rozliczane. Przewodnik po błędach wymienia każdy kod i podpowiada, kiedy ponowić próbę.

Wyślij pierwsze żądanie

Utwórz klucz, doładuj niewielkie saldo i uruchom powyższy przykład w Pythonie albo wypróbuj to samo żądanie bez kodu w playgroundzie Nano Banana 2. Przy złożonych promptach zmień model na gemini-3-pro-image, aby użyć Nano Banana Pro.