Utiliser l’API Nano Banana 2 : clé, requête et résultat

Pour utiliser l’API Nano Banana 2, créez une clé API, envoyez le corps de requête generateContent de Google avec un champ model à un point de terminaison unique, puis interrogez la tâche renvoyée jusqu’à ce que l’URL de l’image soit prête. Les mêmes étapes valent pour Nano Banana Pro et Nano Banana 2 Lite ; seule la valeur de model change.

Ce guide détaille chaque étape avec du code fonctionnel, puis montre comment éditer avec des images de référence et comment confier le travail à un agent de code.

De quoi avez-vous besoin avant la première requête ?

1. Une clé API. Créez-en une sur la page Clés API et conservez-la sur votre serveur. Ne la placez jamais dans du code navigateur.
2. Des crédits. Ajoutez un solde sur la page de facturation. Les crédits n’expirent jamais, et les requêtes échouées ne sont pas facturées.
3. Un ID de modèle. gemini-3.1-flash-image facture un prix fixe par image ; gemini-3.1-flash-image-official facture les tokens. Consultez le guide des prix pour choisir.

export SEEDROUTER_API_KEY="your-key"

Comment envoyer une requête Nano Banana 2 ?

Envoyez la requête en POST à /v1/images/generations. Le corps suit la forme generateContent de Google, plus 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"}
    }
  }'

La réponse est une tâche, pas une image :

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

Si vous appelez déjà l’API de Google, le corps envoyé est le même que celui que vous enverriez à generateContent. L’appel direct à /v1beta/models/...:generateContent sur SeedRouter n’est pas pris en charge ; utilisez ce point de terminaison.

Comment récupérer l’image ?

Interrogez la tâche toutes les quelques secondes jusqu’à ce que status vaille completed ou failed. En Python :

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}.")

Une tâche terminée contient l’URL de l’image dans output.data[0].url, ainsi que l’utilisation de tokens. Avec "responseModalities": ["TEXT", "IMAGE"], tout texte rédigé par le modèle est renvoyé dans output.text. Téléchargez l’image dans votre propre stockage si vous en avez besoin sur le long terme.

Un dépassement de délai pendant l’interrogation ne signifie pas que l’image a échoué. Conservez l’identifiant de tâche et vérifiez-la à nouveau ; soumettre une nouvelle requête revient à payer une seconde image.

Comment éditer une image ou utiliser des références ?

Ajoutez des parties fileData à côté du texte. Chacune contient une URL publique et son type 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 accepte jusqu’à 14 références par requête : images, vidéos ou PDF, de moins de 50 Mo chacune. Les références doivent être des URL ; le base64 inlineData n’est pas accepté. Si une URL ne peut pas être récupérée, la tâche échoue et n’est pas facturée. Pour une édition de suivi, envoyez les tours précédents sous forme d’entrées user et model, et terminez par un nouveau tour user.

Quels réglages comptent le plus ?

La référence de l’API Nano Banana 2 liste chaque champ et chaque limite. Les champs inconnus sont rejetés avant toute facturation, et l’ancrage Google Search (tools) n’est pas encore disponible.

Comment laisser un agent de code utiliser l’API Nano Banana 2 ?

Un agent de code comme Claude Code, Codex ou Cursor peut appeler l’API avec une commande shell ou un court script. SeedRouter ne fournit ni serveur MCP ni skill packagé ; ce prompt constitue toute l’intégration. Exportez d’abord la clé, puis collez :

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.

L’étape d’approbation est importante : l’agent dépense votre solde, il ne doit donc jamais soumettre de lui-même.

Questions fréquentes

Comment obtenir une clé API Nano Banana 2 ?

Connectez-vous, ouvrez la page Clés API et créez une clé. La même clé fonctionne pour Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite et les autres modèles de SeedRouter.

L’API Nano Banana 2 prend-elle en charge les requêtes par lot ?

Envoyez une requête par image et interrogez les tâches en parallèle. Chaque requête renvoie une image, et chaque tâche est facturée séparément.

Quelles erreurs dois-je gérer ?

Un 400 signifie que le corps enfreint une règle, comme un champ inconnu ou une taille non prise en charge, et rien n’est facturé. Une tâche qui se termine en failed contient un message d’erreur et n’est pas facturée non plus. Le guide des erreurs liste chaque code et indique quand réessayer.

Envoyez votre première requête

Créez une clé, ajoutez un petit solde et exécutez l’exemple Python ci-dessus, ou essayez la même requête sans code dans le playground Nano Banana 2. Pour les prompts complexes, remplacez le modèle par gemini-3-pro-image pour utiliser Nano Banana Pro.