Nano Banana 2.1 API

Możliwości

Cennik i kredyty

Każde żądanie generuje jeden obraz. Liczba kredytów zależy od rozdzielczości podanej poniżej. Kredyty są rezerwowane przy przyjęciu zadania, pobierane po sukcesie i zwracane w razie błędu.

Idempotentność żądań nie jest obsługiwana. Każde prawidłowe żądanie POST tworzy nowe, płatne zadanie. Jeśli status wysłanego żądania jest niepewny, należy sprawdzić zwrócony taskId – ponowne wysłanie żądania POST może utworzyć kolejne zadanie.

Uwierzytelnianie

Utwórz klucz API w panelu użytkownika. Pełny klucz zostanie wyświetlony tylko raz. Przechowuj go bezpiecznie na swoim serwerze i przesyłaj w nagłówku jako token Bearer przy każdym żądaniu.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Przed uruchomieniem poniższych przykładów ustaw zmienną środowiskową SEEVIO_API_KEY. Przykłady w JavaScript należy uruchamiać na serwerze przy użyciu Node.js; przykłady w Pythonie korzystają z pakietu requests.

Treść żądania

Parametry wejściowe

Proporcje obrazu (aspect ratio) są domyślnie ustawiane na auto. Każde żądanie generuje dokładnie jeden obraz.

Szybki start

Wyślij to proste żądanie, zapisz zwrócony identyfikator taskId, a następnie użyj poniższego przykładu odpytywania o stan zadania. Liczba kredytów w odpowiedzi na utworzenie zadania to kwota zarezerwowana.

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

Przykładowa odpowiedź na utworzenie zadania

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

Tekst na obraz

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

Obraz na obraz

W przypadku edycji obrazu należy ustawić parametr generation_type na image-to-image i podać adresy w image_urls. Wszystkie pozostałe parametry korzystają z tego samego kontraktu danych.

Zastąp przykładowe adresy URL multimediów z domeny example.com własnymi, publicznie dostępnymi plikami HTTPS. Przykładowe adresy pokazują strukturę żądania i nie są plikami do pobrania.

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

Sprawdź stan zadania

Zastąp przykładowy identyfikator wartością taskId otrzymaną przy tworzeniu zadania. Zapytania zwracają wyłącznie zadania należące do użytkownika powiązanego z danym kluczem API; nieznane lub niedostępne identyfikatory zwracają HTTP 404.

Na początek odpytuj o stan co 10–20 sekund, wydłużaj odstępy w przypadku błędu HTTP 429 i przerwij, gdy status zmieni się na completed lub failed. W środowisku produkcyjnym zalecamy korzystanie z webhooków. Każdy poniższy przykład kodu wykonuje jedno zapytanie.

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

W kolejce

{
  "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
  }
}

Zakończone sukcesem

{
  "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
  }
}

Błąd

Gdy zapytanie zwróci status=failed, oznacza to, że generowanie zakończyło się niepowodzeniem. Przyczynę błędu znajdziesz w polu failed_reason, a wynik zwrotu środków w billing_status. W tym przykładzie status refunded oznacza, że kredyty zostały zwrócone. Pole credits zachowuje pierwotnie zarezerwowaną wartość, a odpowiedź nie zawiera obiektu 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."
}

Linki do wyników są dostępne przez 30 dni od momentu zapisu. Po upływie tego okresu pole results pozostaje puste.

Webhooki

Ustaw parametr callback_url w żądaniu utworzenia, aby otrzymać żądanie POST z formatem JSON, gdy zadanie zostanie zakończone sukcesem lub błędem. Zwróć odpowiedź z kodem 2xx w ciągu 15 sekund. Nieudane doręczenia są ponawiane; powtarzające się wywołania należy przetwarzać idempotentnie na podstawie identyfikatora zadania.

Twój punkt końcowy (callback endpoint) musi akceptować żądania POST z treścią w formacie JSON (Content-Type: application/json).

Utwórz zadanie z wywołaniem zwrotnym (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-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"
}'

Wywołania zwrotne (callbacks) korzystają ze struktury odpowiedzi zapytania o zadanie (task query); powiadomienia o niepowodzeniu ze zwrotem środków zawierają dodatkowo parametr credits_refunded na poziomie głównym. Użyj parametru id do identyfikacji zadania oraz status, aby odróżnić zadania ukończone od nieudanych. Powiadomienia mogą się powtarzać: przetwarzaj je idempotentnie na podstawie id oraz status. Wywołania zwrotne nie są podpisane cyfrowo; zweryfikuj stan zadania za pomocą uwierzytelnionego punktu końcowego zapytania. Brak dostarczenia powiadomienia nie skutkuje zwrotem środków za pomyślnie wykonane zadanie.

Zadanie zakończone: struktura danych pomyślnego wywołania zwrotnego

created_at oznacza czas utworzenia zdarzenia, a task_created_at zadania, w sekundach Unix. Przykłady pokazują zalecane pola; odpowiedzi mogą zawierać dodatkowe pola.

{
  "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
}

Zadanie nie powiodło się: struktura danych błędu wywołania zwrotnego

{
  "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
}

Przykładowy odbiorca

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

Ten przykład dla Next.js odczytuje treść wywołania zwrotnego JSON i bezpośrednio obsługuje zakończone oraz nieudane zadania. W swojej aplikacji dodaj mechanizm trwałości danych oraz deduplikację identyfikatorów zadań (task-ID). Przed potwierdzeniem odbioru wywołania zwrotnego dodaj czasochłonne operacje do kolejki.

Błędy

Błędy HTTP zawierają obiekt error z polami code i message. Pomyślnie przyjęte zadanie może nadal zakończyć się błędem na późniejszym etapie – sprawdzaj stan zadania lub obsłuż wywołanie zwrotne (callback) informujące o błędzie.

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

Błędy używają formatu error.code i error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Błąd 402 insufficient_credits oznacza, że Twoje dostępne kredyty są niewystarczające do realizacji tego żądania.

Limity żądań

Tworzenie zadań: każdy klucz API pozwala domyślnie na maksymalnie 100 żądań na minutę. Niestandardowe limity żądań nie są obecnie dostępne.

Zapytania o zadania: każdy klucz API pozwala domyślnie na maksymalnie 120 żądań na minutę. Zapytania i żądania utworzenia zadań są liczone oddzielnie.

Żądania generowania obrazów i wideo współdzielą ten sam limit zapytań (rate limit) przypisany do klucza API.

Błąd HTTP 429 zawiera nagłówek Retry-After: 60 dla tworzenia zadań oraz Retry-After: 5 dla zapytań o stan. Stosuj algorytm ponawiania z opóźnieniem (backoff) i unikaj zbyt częstego odpytywania.

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

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