nano banana pro api image config no size parameter fr image 0 图示

Éviter les pièges lors de l’invocation de l’API Nano Banana Pro : imageConfig détermine la résolution, ne pas ajouter de paramètre size

par

De nombreux développeurs qui appellent l'API Nano Banana Pro (correspondant au modèle gemini-3-pro-image-preview de Google) pour la première fois tombent dans le même piège : réutiliser le paramètre size: "1024x1024" de l'ère OpenAI / DALL-E. Résultat : soit la résolution de l'image générée ne change pas, soit vous obtenez une erreur 400, soit le paramètre est simplement ignoré par le serveur.

C'est le "bug à haute fréquence" le plus courant lors de l'invocation du modèle Nano Banana Pro. La bonne méthode est la suivante : la résolution est déterminée conjointement par imageConfig.imageSize (définition 1K/2K/4K) et imageConfig.aspectRatio (format 1:1/16:9/…) ; ne transmettez plus aucun champ size. Cet article vous explique tout en 600 mots et vous fournit des codes curl / Python / Node.js prêts à l'emploi.

nano-banana-pro-api-image-config-no-size-parameter-fr 图示

Points clés de l'invocation de l'API Nano Banana Pro

Avant de copier le code, gardez en tête ces trois règles d'or. Une fois comprises, 90 % du contenu de cet article ne sera que des détails :

  1. Nom du modèle : Nano Banana Pro = gemini-3-pro-image-preview (aussi appelé Gemini 3 Pro Image), qui appartient à la série de modèles de génération/édition d'images Google Gemini 3. Certains l'appellent Nano Banana 2, mais c'est fondamentalement la même chose.
  2. Protocole Gemini natif : Il ne s'agit pas du protocole compatible OpenAI Chat Completions. Le chemin de la requête est :generateContent, les champs de haut niveau du corps de la requête sont contents + generationConfig. Il n'y a ni messages, ni champ size de style OpenAI.
  3. Résolution = imageSize × aspectRatio : imageSize contrôle le niveau de définition (512 / 1K / 2K / 4K), et aspectRatio contrôle le format de l'image (1:1 / 16:9 / 9:16 / …). Les deux déterminent ensemble les pixels de sortie finaux.

📌 En résumé : Pour appeler Nano Banana Pro avec le protocole Gemini, oubliez complètement l'habitude du size: "1024x1024" d'OpenAI. Le point de terminaison Nano Banana Pro d'APIYI (apiyi.com) conserve intégralement le protocole natif Gemini ; toute syntaxe imageConfig valide officiellement chez Google fonctionne également sur APIYI.

Aperçu des paramètres clés de Nano Banana Pro

Paramètre Emplacement Rôle Exemple de valeur
imageSize generationConfig.imageConfig Niveau de définition "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig Format d'image "1:1" / "16:9" / "9:16" / "4:3" etc.
responseModalities generationConfig Modalité de sortie ["IMAGE"] (obligatoire)
contents[].parts[].text contents Invite texte Texte libre
contents[].parts[].inline_data contents Image d'entrée (base64) Inclut mime_type et data

⚠️ Le champ size n'est pas dans le tableau : car ce n'est tout simplement pas un paramètre valide du protocole Gemini, ne le transmettez pas.

Pourquoi ne pas ajouter le paramètre size ? Raisons liées à la couche protocolaire

C'est la section la plus importante de cet article. Nous allons décortiquer ce point à travers trois niveaux de lecture.

Niveau protocolaire : Gemini et OpenAI sont deux normes distinctes

L'API d'image d'OpenAI (DALL-E 2/3, gpt-image-1) utilise un paramètre de chaîne de caractères de haut niveau size: "1024x1024", tandis que l'API d'image de Google Gemini 3 est conçue avec un objet imbriqué imageConfig. Ces deux normes sont totalement indépendantes. Nano Banana Pro utilise le protocole natif de Gemini, donc :

  • ❌ size: "1024x1024" —— Le protocole Gemini ne possède pas ce champ.
  • ❌ size: "1K" —— Ce champ n'existe pas.
  • ❌ n: 4 —— Il n'existe pas de champ pour générer "N images à la fois" comme chez OpenAI.
  • ✅ imageConfig.imageSize: "1K" —— Correct.
  • ✅ imageConfig.aspectRatio: "16:9" —— Correct.

Niveau comportemental : que se passe-t-il si vous transmettez size en trop ?

Le traitement côté serveur se résume généralement à trois cas de figure, et aucun n'est celui que vous souhaitez :

  1. Ignoré silencieusement : La passerelle amont considère le champ inconnu comme invalide et le supprime. Vous pensez que votre réglage est pris en compte, mais le résultat est en réalité le format par défaut 1K 1:1.
  2. Erreur 400 immédiate : Une passerelle avec une validation de schéma stricte rejettera directement la requête à cause du champ inconnu.
  3. Impact sur la facturation/routage : Certaines couches de proxy utilisent size comme signal de routage, ce qui peut diriger la requête vers une mauvaise version de point de terminaison.

Niveau ingénierie : la dette technique liée à une maintenance confuse

De nombreuses équipes encapsulent les API d'OpenAI, Gemini, Stability, etc., dans une même couche d'invocation et ont pris l'habitude de réutiliser un "champ size universel". Cela semble élégant, mais c'est un nid à bugs. Il est recommandé, lors de l'appel d'interfaces natives Gemini comme Nano Banana Pro, de passer par une chaîne de conversion dédiée. Mappez explicitement size vers imageConfig.imageSize + imageConfig.aspectRatio au lieu de transmettre le size original tel quel.

💡 Conseil : Lorsque vous utilisez APIYI (apiyi.com) pour appeler Nano Banana Pro, écrivez une petite fonction de conversion de paramètres. Elle transformera les chaînes de caractères habituelles de votre équipe, comme "1024x1024", en imageSize: "1K" + aspectRatio: "1:1", éliminant ainsi le problème à la source.

Tableau complet de correspondance imageSize × aspectRatio

nano-banana-pro-api-image-config-no-size-parameter-fr 图示

Niveaux d'imageSize et facturation

imageSize Résolution max approximative Tokens de sortie Prix unitaire (réf.) Scénarios recommandés
"512" Niveau 512×512 Faible Le moins cher Vignettes / Brouillons
"1K" Niveau 1024×1024 ~1120 ≈ 0,134 $ Recommandé par défaut
"2K" Niveau 2048×2048 ~1120 ≈ 0,134 $ Affiches HD
"4K" Niveau 4096×4096 ~2000 ≈ 0,24 $ (80% plus cher) Qualité impression

💰 Note sur les coûts : Le format 4K est environ 80 % plus cher que le 1K/2K, ne l'utilisez pas systématiquement sans réfléchir. Pour la grande majorité des scénarios Web/App, le 1K suffit amplement ; passez au 4K uniquement pour les besoins en très haute résolution. Les tarifs officiels les plus récents sont disponibles sur le site d'APIYI (apiyi.com).

Liste complète des ratios (aspectRatio) supportés

Ratio Usage
"1:1" Avatar / Image carrée réseaux sociaux
"16:9" Couverture vidéo paysage / Fond d'écran PC
"9:16" Vidéo courte portrait / Fond d'écran mobile
"4:3" Format photo classique paysage
"3:4" Format photo classique portrait
"3:2" / "2:3" Ratio standard DSLR
"4:5" / "5:4" Image Instagram
"21:9" Format cinéma ultra-large
"1:4" / "4:1" Bannière allongée
"1:8" / "8:1" Usage spécial très allongé

Combinaisons courantes → Correspondance en pixels finaux

imageSize aspectRatio Pixels de sortie approximatifs
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

Note : Les pixels réels peuvent subir un ajustement mineur de ±N pixels en raison des règles d'alignement internes du modèle, mais cela n'affecte pas la netteté visuelle du niveau de résolution.

Voici le guide pour effectuer correctement les appels API vers Nano Banana Pro.

Code d'appel correct pour l'API Nano Banana Pro

Voici des exemples minimaux fonctionnels dans trois langages. Ces trois exemples effectuent la même opération : envoi d'une image source + une invite, pour générer une image en 1K au format 1:1.

Version curl (la plus directe pour le débogage)

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer VOTRE-CLE-APIYI" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(base64 de l'\''image source)"
          }
        },
        {
          "text": "Transforme cette image en style cyberpunk, en conservant la pose du personnage"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Version Python (utilisation recommandée de requests, sans dépendance SDK)

import base64
import requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer VOTRE-CLE-APIYI",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "Transforme cette image en style cyberpunk, en conservant la pose du personnage"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Version Node.js (utilisation de fetch natif pour éviter que le SDK ne supprime imageConfig)

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer VOTRE-CLE-APIYI",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "Transforme cette image en style cyberpunk, en conservant la pose du personnage" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 Pourquoi privilégier fetch ou requests natifs : Certains SDK (dont d'anciennes versions de LiteLLM ou du SDK Google Node) filtrent imageConfig comme un champ inconnu, rendant imageSize ou aspectRatio inopérants. Construire le corps JSON manuellement garantit que rien n'est supprimé. Si vous utilisez un SDK, assurez-vous d'être à jour et vérifiez le corps de la requête via un intercepteur.

Liste de contrôle : 6 erreurs fréquentes

nano-banana-pro-api-image-config-no-size-parameter-fr 图示

Erreur 1 : Utiliser le paramètre size style OpenAI

// ❌ Erreur : 'size' n'est pas un champ valide dans le protocole Gemini
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ Correct : Supprimez 'size', gardez uniquement 'imageConfig'
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

Erreur 2 : Utiliser des underscores (snake_case)

Les champs de imageConfig pour Gemini 3 utilisent la casse CamelCase : imageSize, aspectRatio, responseModalities.

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

Erreur 3 : imageConfig supprimé par le SDK

Comme mentionné, certains SDK filtrent les champs inconnus. Pour diagnostiquer :

  1. Affichez le corps HTTP réel avant l'envoi.
  2. Utilisez un proxy (mitmproxy/Charles) pour inspecter la requête sortante.
  3. Si le champ disparaît, passez au fetch ou requests natif.

Erreur 4 : Oublier responseModalities

// ❌ Sans 'responseModalities', vous pourriez recevoir du texte au lieu d'une image
{ "generationConfig": { "imageConfig": {...} } }

// ✅ Déclarez explicitement que la modalité de retour inclut 'IMAGE'
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

Erreur 5 : Pas de stratégie de "backoff" exponentiel en cas d'erreur 429

En cas de saturation, l'API renvoie une erreur 429. Ne réessayez pas immédiatement, utilisez un délai exponentiel (3s → 6s → 12s) :

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3s, 6s, 12s

Erreur 6 : Mauvais emplacement pour les images de référence

Nano Banana Pro gère plusieurs images. Toutes doivent être ajoutées comme des éléments inline_data distincts dans le tableau parts, avec l'invite textuelle placée en dernier :

// ✅ Correct : Images d'abord, texte à la fin
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "base64 image source" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 image ref 1" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 image ref 2" } },
  { "text": "Applique le style de l'image ref 1 à l'image source, en utilisant la composition de l'image ref 2" }
]

🧰 Résumé : Intégrez ces 6 points dans votre "Checklist Nano Banana Pro". L'API APIYI (apiyi.com) suit strictement le protocole Gemini, ces conseils sont donc universels.

Décomposition du flux d'invocation utilisateur : où se situe le risque d'erreur ?

nano-banana-pro-api-image-config-no-size-parameter-fr 图示

Beaucoup de lecteurs partagent des journaux d'invocation quasi identiques au flux suivant :

Frontend POST /api/generate
  → server.js extrait les paramètres
  → Vérifie si modelKey.startsWith('nano-banana')
  → _generateViaGemini() assemble le corps de la requête
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → Retour / Réessai

Voici les points critiques où les erreurs surviennent le plus souvent :

Étape Problème courant Conseil
Paramètres frontend Transmission habituelle de size: "1024x1024" Séparez en deux champs : imageSize + aspectRatio
Assemblage body server.js Transmission erronée du champ size à Gemini Supprimez explicitement size dans la fonction d'assemblage
Routage du modèle Routage de nano-banana vers 1.5 au lieu de 3 Pro Utilisez strictement le nom gemini-3-pro-image-preview
Envoi de la requête Utilisation d'une version SDK avec validation de schéma Passez au fetch natif ou mettez à jour le SDK
Gestion des erreurs Erreur 429 renvoyée directement à l'utilisateur Implémentez un réessai avec backoff exponentiel (3 fois)
Analyse de réponse Lecture par défaut en text au lieu de IMAGE Chemin correct : candidates[0].content.parts[0].inline_data.data

📋 En résumé : Votre structure de flux est correcte. Il suffit de supprimer ce champ size superflu lors de l'extraction des paramètres et de vérifier que server.js ne le réinsère pas en dehors de generationConfig. Votre chaîne sera alors parfaitement propre.

FAQ – Questions fréquentes

Q1 : Nano Banana Pro et Nano Banana 2 sont-ils la même chose ?
Oui. Beaucoup dans la communauté appellent Gemini 3 Pro Image (gemini-3-pro-image-preview) "Nano Banana 2" ou "Nano Banana Pro". Ces trois appellations désignent le même modèle. Sur APIYI (apiyi.com), référez-vous toujours à la documentation officielle pour le nom du modèle.

Q2 : Que se passe-t-il si je ne transmets pas imageConfig ?
Le modèle utilisera ses valeurs par défaut (généralement 1K + 1:1). Si la résolution vous importe peu, vous pouvez l'omettre ; sinon, vous devez transmettre explicitement imageConfig.

Q3 : Puis-je utiliser le protocole Gemini tout en transmettant size comme avec OpenAI ?
Non, ce n'est pas fiable. Le protocole Gemini ne possède pas de champ size ; le mélanger ne fera que provoquer des comportements imprévisibles. Utiliser imageConfig.imageSize + imageConfig.aspectRatio est la méthode la plus sûre.

Q4 : Choisir 4K pour imageSize garantit-il une meilleure qualité ?
Les détails seront plus riches, mais le coût est presque doublé (~0,24 $ contre 0,134 $) et le temps de génération est plus long. Pour des illustrations Web/App, 1K ou 2K suffisent généralement. Testez sur des images réelles et comparez visuellement avant de décider.

Q5 : Quelle est la différence entre appeler Nano Banana Pro via APIYI (apiyi.com) et via l'API Google officielle ?
APIYI propose une authentification unifiée de style OpenAI (Bearer Token), un accès fluide depuis la Chine et une facturation centralisée, tout en conservant strictement le format natif de Gemini. Cela signifie que imageConfig / aspectRatio / responseModalities fonctionnent exactement comme dans la documentation officielle de Google.

Q6 : Pourquoi mon image sort-elle en 1K alors que j'ai réglé imageSize: "2K" ?
Trois causes fréquentes : (1) Utilisation d'un SDK qui filtre les champs inconnus, (2) Nom de champ écrit image_size, (3) Erreur dans l'imbrication de generationConfig. Capturez le paquet réseau réel pour vérifier si le corps est conforme avant de déboguer le serveur.

Q7 : Que faire face au bridage (429) en amont ?
Mettez en place un réessai avec backoff exponentiel (3s/6s/12s). Si votre service est sensible à la latence, envisagez de changer de groupe dans votre espace de travail APIYI (apiyi.com) ou de demander un quota dédié. Ne faites jamais de boucle infinie de réessai immédiat, cela ne ferait que prolonger le bridage.

Q8 : Y a-t-il une limite au nombre d'images en entrée ?
L'interface Gemini 3 image limite la taille totale des images par requête (généralement en Mo, selon les spécifications officielles). Il est conseillé de ne pas dépasser 4 à 5 images de référence, en contrôlant leur taille (redimensionnement avant conversion en base64), sous peine de déclencher une erreur 413 ou un timeout.

Résumé : Gravez la "méthode des deux paramètres de résolution" dans votre mémoire musculaire

S'il ne fallait retenir qu'une seule chose, ce serait celle-ci :

La résolution de sortie finale de Nano Banana Pro = imageConfig.imageSize × imageConfig.aspectRatio. Ne transmettez plus aucun champ size de style OpenAI.

Checklist complète :

  • ✅ Nom du modèle : gemini-3-pro-image-preview
  • ✅ Point de terminaison : /v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities doit impérativement inclure "IMAGE"
  • ✅ Placez les entrées multi-images dans le tableau parts, et l'invite textuelle à la fin
  • ✅ En cas de limitation de débit 429, utilisez un backoff exponentiel (3s/6s/12s)
  • ❌ Ne transmettez pas size: "1024x1024"
  • ❌ N'écrivez pas image_size / aspect_ratio (le format snake_case est incorrect)
  • ❌ Ne vous fiez pas aux anciens SDK qui filtrent les champs inconnus, vérifiez d'abord via une capture réseau

📢 Dernier mot : Si vous accédez à Nano Banana Pro via APIYI (apiyi.com), copiez simplement les modèles de code curl / Python / Node.js fournis dans cet article. Tous les paramètres sont strictement conformes au protocole natif de Gemini : copiez-collez, modifiez votre clé API et lancez le tout.

Auteur : Équipe APIYI · Compilation continue des meilleures pratiques pour l'invocation du modèle d'IA · apiyi.com

Laisser un commentaire