Pratique de l’API de génération d’images par dialogue multi-tours Nano Banana Pro : 3 étapes pour configurer la génération d’images avec fenêtre de contexte

Note de l'auteur : Analyse approfondie de la structure des champs, de la construction du tableau contents, du mécanisme thoughtSignature et de la mise en œuvre pratique de l'API de génération d'images multi-tours Nano Banana Pro (gemini-3-pro-image-preview).

De nombreux développeurs rencontrant Nano Banana Pro pour la première fois font face à la même confusion : sur l'interface web gemini.google.com, on peut enchaîner les requêtes comme « change le fond pour un coucher de soleil » ou « ajoute un chat », et le modèle se souvient parfaitement de l'image précédente. Pourtant, lors de l'appel à l'API officielle, le modèle semble avoir une amnésie totale. La raison est que l'API Gemini est intrinsèquement sans état ; le contexte multi-tours doit être construit manuellement par l'appelant. Cet article explique en détail les champs sous-jacents de l'API de génération d'images multi-tours, les implémentations via le SDK Python et REST, ainsi que le mécanisme crucial thoughtSignature, pour vous aider à mettre en place une expérience de génération contextuelle aussi fluide que sur le web en 3 étapes.

Valeur ajoutée : Après avoir lu cet article, vous maîtriserez la construction correcte du tableau contents, vous saurez implémenter des flux de travail multi-tours « d'édition basée sur l'image précédente » dans vos applications, et vous éviterez les trois pièges classiques : « oubli de l'image », « gaspillage de jetons » et « perte de signature ».

Points clés de la génération d'images multi-tours Nano Banana Pro

Différence fondamentale entre la génération multi-tours et l'Agent web

gemini.google.com est une application Agent construite par Google. Elle gère pour vous, côté front-end, un « état de conversation » complet (incluant les textes de chaque tour, les images générées et la signature de réflexion). À chaque nouvelle saisie, cet Agent envoie tout l'historique au modèle sous-jacent en une seule fois. C'est pourquoi l'expérience sur le web est si fluide : tout le travail de « mémoire » est pris en charge par l'Agent.

Lorsque vous appelez directement l'API generateContent, vous obtenez une interface d'invocation « brute ». Chaque requête HTTP est une inférence indépendante, et le modèle n'a aucune notion de vos échanges précédents. Pour reproduire l'expérience multi-tours du web, vous devez essentiellement implémenter votre propre Agent dans votre code : remplissez les messages user historiques et les réponses model (incluant images et signatures) dans contents selon les spécifications, puis lancez la requête.

Analyse détaillée de la structure des champs pour la génération d'images multi-tours avec Nano Banana Pro

Spécifications essentielles du tableau contents

Le champ contents est la norme de l'API Gemini pour représenter l'historique d'une conversation. Il s'agit d'un tableau JSON où chaque élément correspond à une intervention :

Voici à quoi ressemble un corps de requête complet pour un dialogue en deux tours :

{
  "contents": [
    {"role": "user", "parts": [{"text": "Génère un golden retriever courant sur la plage"}]},
    {"role": "model", "parts": [
      {"inline_data": {"mime_type": "image/png", "data": "<base64 de la première image générée>"}},
      {"thought_signature": "<signature cryptographique>"}
    ]},
    {"role": "user", "parts": [{"text": "Change la scène pour le crépuscule"}]}
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
  }
}

Deux méthodes pour renvoyer des images

Lors du deuxième tour, le modèle doit pouvoir « voir » l'image générée au premier tour. Nano Banana Pro prend en charge deux méthodes :

# Méthode 1 : inline_data avec base64 intégré (idéal pour les petites images, simple et direct)
{
    "inline_data": {
        "mime_type": "image/png",
        "data": base64.b64encode(image_bytes).decode()
    }
}

# Méthode 2 : file_data référençant une ressource téléchargée via l'API Files (idéal pour les grandes images ou la réutilisation)
{
    "file_data": {
        "mime_type": "image/png",
        "file_uri": "files/abc123xyz"
    }
}

Conseil clé : inline_data est la méthode la plus courante pour les appels directs dans des scénarios ponctuels ; le mode file_data est préférable si vous devez réutiliser la même image volumineuse sur plusieurs tours, ce qui permet de réduire considérablement la taille de la requête et les coûts de transfert.

Prise en main rapide de la génération d'images multi-tours avec Nano Banana Pro

Exemple minimaliste (gestion automatique par le SDK Python)

Si vous utilisez le SDK Python officiel, seulement 10 lignes suffisent :

from google import genai

client = genai.Client(api_key="VOTRE_CLE_API")
chat = client.chats.create(model="gemini-3-pro-image-preview")

# Premier tour : génération de l'image initiale
r1 = chat.send_message("Génère un golden retriever courant sur la plage")

# Deuxième tour : édition basée sur la première image (l'objet chat conserve l'historique automatiquement)
r2 = chat.send_message("Change la scène pour le crépuscule et ajoute une mouette en vol")

# Troisième tour : modification supplémentaire
r3 = chat.send_message("Change la couleur du chien en brun foncé")

L'objet chat gère en interne la liste complète des contents (y compris la thoughtSignature de chaque tour), vous n'avez donc pas à vous soucier des détails techniques. Chaque appel à send_message inclut automatiquement l'historique.

import openai
import base64

client = openai.OpenAI(
    api_key="VOTRE_CLE_API",
    base_url="https://vip.apiyi.com/v1"
)

# Maintenir une liste locale de messages (le concept équivalent à contents)
messages = [
    {"role": "user", "content": "Génère un golden retriever courant sur la plage"}
]

# Premier tour
response1 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)
img1_url = response1.choices[0].message.content  # Extraire l'URL ou le base64 de l'image

# Ajouter la réponse du modèle à l'historique
messages.append({"role": "assistant", "content": img1_url})

# Deuxième tour : ajout d'une nouvelle instruction
messages.append({"role": "user", "content": "Change la scène pour le crépuscule"})
response2 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

# Troisième tour...
messages.append({"role": "assistant", "content": response2.choices[0].message.content})
messages.append({"role": "user", "content": "Ajoute une mouette en vol"})
response3 = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=messages
)

Recommandation : Pour les scénarios d'édition multi-tours, nous vous conseillons d'utiliser l'objet chat du SDK ou de maintenir une liste locale de messages pour éviter de concaténer manuellement les contents. Vous pouvez vous inscrire sur APIYI (apiyi.com) pour obtenir un crédit gratuit, tester avec le SDK, puis envisager des optimisations REST par la suite.

Construction manuelle de requêtes REST pour le dialogue multi-tours avec Nano Banana Pro

Implémentation REST pure sans dépendance au SDK

Dans certains scénarios (comme le proxy API côté serveur, les nœuds ComfyUI ou les plateformes low-code), il n'est pas possible d'utiliser le SDK officiel. Vous devez alors construire vos requêtes REST manuellement. Voici l'appel curl complet :

# Premier tour : génération d'image à partir d'une instruction textuelle
curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Générer un golden retriever courant sur la plage"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

# La réponse contiendra : parts[0].inline_data.data (image en base64)
# ainsi que parts[0].thought_signature

Pour le deuxième tour, vous devez impérativement réinsérer l'intégralité de la réponse du modèle du premier tour (incluant l'image et la signature) dans le champ contents :

curl -X POST \
  "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Générer un golden retriever courant sur la plage"}]},
      {"role": "model", "parts": [
        {"inline_data": {"mime_type": "image/png", "data": "<base64 retourné au premier tour>"}},
        {"thought_signature": "<signature retournée au premier tour>"}
      ]},
      {"role": "user", "parts": [{"text": "Change la scène pour le coucher du soleil"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

Comparaison des trois modes d'invocation

Note sur les données : Le graphique ci-dessus illustre les différences fondamentales entre la gestion automatique par un Agent et la gestion manuelle via API. Vous pouvez comparer les performances réelles de ces deux méthodes directement sur la plateforme APIYI (apiyi.com).

Mécanisme thoughtSignature pour la génération d'images en dialogue multi-tours avec Nano Banana Pro

Qu'est-ce que thoughtSignature ?

thoughtSignature est une « signature de réflexion chiffrée » introduite avec la série Gemini 3. Il s'agit d'un encodage compact de l'état de raisonnement interne du modèle. Bien qu'il soit illisible pour l'œil humain, le modèle l'utilise pour restaurer rapidement le contexte lors du tour suivant. Ses rôles principaux sont :

• Préservation des décisions clés : Par exemple, si le modèle « décide » d'utiliser des tons clairs au premier tour, il héritera de ce style au second tour grâce à la signature.
• Amélioration de la cohérence : Les personnages, les scènes et la composition restent stables lors des modifications multi-tours.
• Économie de jetons (tokens) : Évite de répéter constamment « conserver le style original » dans l'invite.

Quand est-il indispensable d'inclure la signature ?

Pratique : Modèle de code pour gérer manuellement la signature

import requests
import base64
import json

API_BASE = "https://vip.apiyi.com/v1beta"
MODEL = "gemini-3-pro-image-preview"
HEADERS = {
    "x-goog-api-key": "VOTRE_CLE_API",
    "Content-Type": "application/json"
}

class NanoBananaChat:
    """Client de chat minimaliste gérant manuellement contents + signature"""
    def __init__(self):
        self.contents = []

    def send(self, text: str, attach_image_b64: str = None) -> dict:
        # Construction du message utilisateur pour ce tour
        user_parts = [{"text": text}]
        if attach_image_b64:
            user_parts.append({
                "inline_data": {"mime_type": "image/png", "data": attach_image_b64}
            })
        self.contents.append({"role": "user", "parts": user_parts})

        # Envoi de la requête
        resp = requests.post(
            f"{API_BASE}/models/{MODEL}:generateContent",
            headers=HEADERS,
            json={
                "contents": self.contents,
                "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
            }
        ).json()

        # Ajout de la réponse du modèle (incluant la signature) dans contents
        model_parts = resp["candidates"][0]["content"]["parts"]
        self.contents.append({"role": "model", "parts": model_parts})
        return model_parts

# Exemple d'utilisation
chat = NanoBananaChat()
parts1 = chat.send("Génère un golden retriever courant sur une plage")
parts2 = chat.send("Change la scène pour un coucher de soleil")  # Historique et signature inclus automatiquement
parts3 = chat.send("Ajoute une mouette en plein vol")

Conseil d'optimisation : Lors de l'utilisation via APIYI (apiyi.com), la plateforme transmettra le champ thought_signature tel quel. Les développeurs doivent simplement s'assurer d'ajouter l'intégralité du tableau model parts à contents, sans avoir à se soucier du contenu spécifique de la signature.

Cas d'utilisation pratique : Génération d'images par conversation multi-tours avec Nano Banana Pro

Scénario 1 : Conception de marque progressive

Un besoin courant des équipes marketing : partir d'une image conceptuelle de produit et ajuster progressivement le texte, les couleurs et la mise en page. L'avantage de l'API de génération d'images par conversation multi-tours est qu'il suffit de décrire les « changements incrémentaux » à chaque étape, sans avoir à redécrire l'image entière :

chat = client.chats.create(model="gemini-3-pro-image-preview")

chat.send_message("Conçois une affiche pour une marque de café avec un fond dégradé bleu foncé, place le produit sur la gauche")
chat.send_message("Change le titre par « Awaken Your Morning »")
chat.send_message("Ajoute un espace réservé pour un QR code en bas à droite")
chat.send_message("Rends le style global plus moderne et supprime les bordures décoratives")

Scénario 2 : Édition multi-tours basée sur des images de référence

Nano Banana Pro prend en charge jusqu'à 14 images de référence par requête. Combiné à une conversation multi-tours, cela permet de construire des flux de travail de fusion d'images puissants :

# Téléchargement d'un portrait + une image de référence de vêtement
chat.send_message([
    "Habille la personne de la première image avec la tenue de la deuxième image",
    {"inline_data": {"mime_type": "image/png", "data": person_b64}},
    {"inline_data": {"mime_type": "image/png", "data": outfit_b64}}
])

# Ajustements ultérieurs
chat.send_message("Change l'encolure pour un col en V")
chat.send_message("Remplace l'arrière-plan par un gris épuré")

Scénario 3 : Restauration de l'historique entre les sessions

Si un utilisateur ferme la page et la rouvre, et souhaite poursuivre la conversation précédente, vous devez persister le tableau contents dans votre base de données :

import json

# Sauvegarde
with open(f"sessions/{user_id}.json", "w") as f:
    json.dump(chat.get_history(), f)

# Restauration
with open(f"sessions/{user_id}.json") as f:
    history = json.load(f)
restored_chat = client.chats.create(
    model="gemini-3-pro-image-preview",
    history=history
)
restored_chat.send_message("Continue comme avant, mais rends l'arrière-plan un peu plus lumineux")

Limites de la fenêtre de contexte

Conseil pratique : Lorsque la conversation dépasse 8 à 10 tours, il est conseillé de « tronquer » activement l'historique ancien ou de le remplacer par un résumé généré par un Grand modèle de langage, sinon le nombre de tokens approchera rapidement la limite de 64K. En environnement de production, assurez-vous d'intégrer un compteur de tokens pour décider de la troncature côté client.

Questions fréquentes

Résumé

Les points clés de l'API de génération d'images par dialogue multi-tours Nano Banana Pro :

1. Nature sans état : L'API ne mémorise aucun historique ; c'est à l'appelant de gérer le tableau contents.
2. Alternance des rôles : Les rôles user et model doivent alterner strictement, et chaque tour de parts peut combiner texte, image et signature.
3. Renvoi d'image : L'image générée au tour précédent doit être réinjectée sous forme d'inline_data, sinon le modèle ne pourra pas la "voir".
4. Mécanisme de signature : La thought_signature est essentielle pour la cohérence multi-tours ; en mode REST, elle doit être transmise manuellement.
5. Simplification par le SDK : L'objet chat du SDK Python officiel gère automatiquement tous ces détails.

Pour les développeurs souhaitant implémenter rapidement une expérience web, la meilleure approche consiste à utiliser l'objet chat du SDK officiel ou le mode messages de l'interface compatible OpenAI, afin d'éviter la complexité liée à la construction manuelle des requêtes REST.

Nous vous recommandons d'accéder aux capacités de génération d'images par dialogue multi-tours de Nano Banana Pro via APIYI (apiyi.com). La plateforme prend en charge à la fois les champs natifs Gemini et le mode compatible OpenAI, offre des crédits de test gratuits et facilite la validation rapide des effets d'édition multi-tours ainsi que la migration fluide de vos projets existants.

📚 Références

1. Documentation officielle de l'API Gemini pour la génération d'images : Instructions faisant autorité sur la génération d'images par dialogue multi-tours.

   • Lien : ai.google.dev/gemini-api/docs/image-generation
   • Description : Inclut les spécifications du champ contents, ainsi que des exemples complets pour le SDK Python et REST.

2. Fiche technique du modèle Gemini 3 Pro Image Preview : Détails sur les capacités et les limites du modèle.

   • Lien : ai.google.dev/gemini-api/docs/models/gemini-3-pro-image-preview
   • Description : Paramètres clés tels que la fenêtre de contexte, la résolution et le nombre d'images de référence.

3. Forum Google AI Developers – Multi-turn Nano Banana : Exemples pratiques de la communauté.

   • Lien : discuss.ai.google.dev/t/multi-turn-nano-banana-example
   • Description : Discussions entre développeurs sur les meilleures pratiques pour le dialogue multi-tours.

4. Documentation Vertex AI Gemini 3 Pro Image : Référence pour le déploiement en entreprise.

   • Lien : docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
   • Description : Couvre les usages avancés, notamment la thought_signature et les références file_data.

5. Documentation d'accès APIYI pour Nano Banana Pro : Prise en main rapide pour les développeurs.

   • Lien : help.apiyi.com
   • Description : Inclut des exemples pour les deux modes : interface compatible OpenAI et interface native Gemini.

Auteur : Équipe technique APIYI
Échanges techniques : N'hésitez pas à partager dans les commentaires les problèmes concrets que vous avez rencontrés lors de la génération d'images par dialogue multi-tours. Pour plus d'astuces de configuration sur Nano Banana Pro, consultez le centre de documentation APIYI sur docs.apiyi.com.