Note de l'auteur : décryptage champ par champ des messages d'erreur IMAGE_SAFETY renvoyés par l'API Nano Banana Pro. Analyse du mécanisme de filtrage de sécurité à deux niveaux, de la logique de facturation des jetons et de 8 méthodes pratiques pour améliorer le taux de réussite de génération.
Lorsque vous générez des images avec l'API Nano Banana Pro, vous avez peut-être déjà rencontré cette réponse déroutante : alors que votre invite ne contient aucun contenu sensible, le système renvoie finishReason: IMAGE_SAFETY, et l'image est bloquée par le filtre de sécurité. Plus frustrant encore, le champ thoughtsTokenCount: 173 dans la réponse indique que le modèle a bien terminé sa réflexion, mais que l'image a été "abattue" au dernier moment. Cet article analyse cette erreur champ par champ, explique le mécanisme de filtrage de sécurité à deux niveaux de Google, la logique de facturation des jetons en cas de blocage, et comment augmenter votre taux de réussite.
Valeur ajoutée : Après avoir lu cet article, vous comprendrez la signification de chaque champ de l'erreur IMAGE_SAFETY, vous saurez si vous êtes facturé en cas de blocage et comment optimiser vos invites pour augmenter votre taux de réussite à 70-80 %.
Analyse détaillée des champs de l'erreur IMAGE_SAFETY
Commençons par clarifier la signification de chaque champ dans cette réponse.
| Champ | Valeur | Signification |
|---|---|---|
content.parts |
null |
Aucun contenu retourné (image bloquée) |
finishReason |
IMAGE_SAFETY |
Déclenchement du filtre de sécurité de sortie de second niveau |
finishMessage |
"Unable to show…" | Message officiel de Google : violation de la politique d'utilisation de l'IA générative |
promptTokenCount |
276 | L'entrée a consommé 276 jetons |
candidatesTokenCount |
0 | Jetons de sortie à 0 (image bloquée, aucune génération) |
totalTokenCount |
449 | Total de 449 jetons (276 en entrée + 173 de réflexion) |
thoughtsTokenCount |
173 | Le processus de réflexion du modèle a consommé 173 jetons |
promptTokensDetails |
TEXT:18, IMAGE:258 | 18 jetons de texte + 258 jetons d'image (image de référence) |
modelVersion |
gemini-3-pro-image-preview | Modèle Nano Banana Pro |
Les 3 signaux clés de l'erreur IMAGE_SAFETY
Signal 1 : thoughtsTokenCount: 173 — Le modèle a bien réfléchi
Cela indique que votre invite a franchi la première barrière de sécurité (côté entrée), que le modèle a entamé son processus de raisonnement (Thinking) et a même commencé à générer l'image, mais qu'il a été bloqué par le filtre de sécurité de second niveau lors de la sortie finale. Le problème ne vient pas de votre invite, mais du contenu que le modèle "a essayé de dessiner".
Signal 2 : candidatesTokenCount: 0 — Sortie nulle
Une fois l'image bloquée, le nombre de jetons de sortie est comptabilisé à 0. Selon Google, "You will not be charged for blocked images" (les images bloquées ne sont pas facturées). Attention toutefois : la facturation des jetons d'entrée (276) et de réflexion (173) dépend de la logique de facturation spécifique.
Signal 3 : IMAGE: 258 — Vous avez fourni une image de référence
Votre requête contient une image de référence (consommant 258 jetons d'image). Cela signifie que vous effectuez probablement une opération d'image vers image plutôt qu'une simple génération de texte vers image. Le filtrage de sécurité pour l'édition d'images est généralement plus strict que pour le texte seul, car l'image de référence elle-même est soumise à une vérification de sécurité.
Le mécanisme de filtrage de sécurité à deux niveaux de Google
Pour comprendre l'erreur IMAGE_SAFETY, il faut savoir que le filtrage de sécurité de Google comporte deux niveaux, et que le second ne peut pas être désactivé.
Premier niveau : Paramètres de sécurité d'entrée configurables
| Dimension | Description | Configurable |
|---|---|---|
| Emplacement | Côté entrée (invite) | Oui |
| Objet filtré | Texte et images soumis par l'utilisateur | Oui |
| Réglage possible | BLOCK_NONE (aucun blocage) | Oui |
| Comportement | Requête rejetée immédiatement, aucun jeton consommé | — |
Vous pouvez réduire la sensibilité du premier niveau en réglant safety_settings sur BLOCK_NONE via les paramètres de l'API.
Second niveau : Filtrage de sécurité de sortie non configurable
| Dimension | Description | Configurable |
|---|---|---|
| Emplacement | Côté sortie (image générée) | Non |
| Objet filtré | Contenu de l'image générée par le modèle | Non |
| Désactivation | Impossible, obligatoire pour tous les utilisateurs | Non |
| Comportement | finishReason: IMAGE_SAFETY, parts: null |
— |
L'erreur IMAGE_SAFETY survient lorsque ce second niveau est déclenché. Votre invite a passé le premier niveau, le modèle a terminé sa réflexion (173 jetons) et a généré l'image, mais celle-ci a été interceptée avant la sortie finale.
Google reconnaît que ce filtre est devenu "plus prudent que prévu", entraînant de nombreux faux positifs — même des invites aussi simples qu'"un chien" ou "un bol de céréales" peuvent être bloquées.
Est-ce que l'on est facturé quand IMAGE_SAFETY bloque une requête ?
C'est la question concrète qui préoccupe le plus les développeurs.
Règles de facturation IMAGE_SAFETY pour Nano Banana Pro
| Élément facturé | Facturé en cas de blocage ? | Explication |
|---|---|---|
| Frais de génération d'image | Non facturé | Google précise clairement : "You will not be charged for blocked images" |
| Tokens de sortie | Non facturé | candidatesTokenCount: 0, pas de sortie, pas de frais |
| Tokens d'entrée | Facturation possible (négligeable) | 276 tokens × 0,25 $ / M ≈ 0,00007 $ (négligeable) |
| Tokens de réflexion | Selon la logique de facturation | 173 tokens, l'API Gemini peut les inclure dans les candidates |
Conclusion : Lorsqu'une requête est bloquée par IMAGE_SAFETY, les coûts principaux (frais de génération d'image et tokens de sortie) ne sont pas générés. Les frais liés aux tokens d'entrée sont extrêmement faibles (moins d'un dix-millième de dollar) et peuvent être ignorés.
La garantie supplémentaire d'APIYI : Lorsque vous passez par APIYI (apiyi.com), aucun frais n'est prélevé en cas d'échec de génération, y compris lors d'un blocage par IMAGE_SAFETY. Vous ne payez que pour les images générées avec succès.
8 méthodes pour améliorer le taux de réussite de IMAGE_SAFETY
Puisque le second niveau de filtrage de sécurité ne peut pas être désactivé, nous devons utiliser des méthodes indirectes pour améliorer le taux de réussite.
Méthode 1 : Configurer BLOCK_NONE pour désactiver le premier niveau
Assurez-vous d'abord que le premier niveau n'ajoute pas de blocages inutiles :
from google.genai import types
# Configuration des paramètres de sécurité pour autoriser le contenu
safety_settings = [
types.SafetySetting(
category="HARM_CATEGORY_HARASSMENT",
threshold="BLOCK_NONE"
),
types.SafetySetting(
category="HARM_CATEGORY_HATE_SPEECH",
threshold="BLOCK_NONE"
),
types.SafetySetting(
category="HARM_CATEGORY_SEXUALLY_EXPLICIT",
threshold="BLOCK_NONE"
),
types.SafetySetting(
category="HARM_CATEGORY_DANGEROUS_CONTENT",
threshold="BLOCK_NONE"
),
]
Méthode 2 : Ajouter des détails précis à votre invite
Les invites vagues déclenchent plus facilement les filtres de sécurité. Ajouter des détails précis guide le modèle vers une génération plus "sûre" :
❌ "Une femme"
→ Le modèle peut générer un contenu jugé inapproprié par le filtre
✅ "Une femme portant un tailleur professionnel, travaillant dans un bureau moderne,
lumière naturelle, style illustration numérique"
→ Scène précise + description vestimentaire + style artistique → Taux de réussite largement amélioré
Méthodes 3 à 8 : Stratégies d'optimisation avancées
| Méthode | Action | Effet attendu |
|---|---|---|
| Méthode 3 : Ajouter un style artistique | Ajouter "digital illustration style" ou "watercolor style" à la fin | Réduit le réalisme → Moins de déclenchements |
| Méthode 4 : Spécifier le contexte | Ajouter une description de scène claire ("dans un parc", "au bureau") | Limite la marge d'interprétation du modèle |
| Méthode 5 : Éviter les descriptions de peau | Utiliser "formal attire" ou "winter clothing" au lieu de descriptions vagues | Évite directement les zones sensibles |
| Méthode 6 : Utiliser des invites en anglais | Le calibrage du filtre de sécurité est plus précis en anglais | Réduit les faux positifs |
| Méthode 7 : Réessayer automatiquement avec une autre formulation | Réécrire l'invite automatiquement après un échec | Améliore le taux de réussite global |
| Méthode 8 : Passer par APIYI | APIYI propose une configuration optimisée des paramètres de sécurité | Taux de réussite global supérieur |
Comparaison avant/après optimisation de l'invite
| Scène | Avant optimisation (faible taux) | Après optimisation (taux élevé) |
|---|---|---|
| Personnage | "Une fille en maillot de bain" | "Une femme en tenue de sport s'entraînant dans une salle de sport, style illustration numérique" |
| Nourriture | "Un steak" | "Un steak mi-cuit sur une assiette en porcelaine blanche, table de restaurant, photographie culinaire professionnelle" |
| Animal | "Un chien" | "Un golden retriever attrapant un frisbee dans un jardin de banlieue, soleil d'après-midi, style illustration numérique" |
| E-commerce | "Mannequin en lingerie" | "Photo à plat d'une brassière de sport blanche, fond blanc pur, sans mannequin, photographie de produit" |
🎯 Principe fondamental : Plus l'invite est précise = moins le modèle a de liberté d'interprétation = moins de risques de déclencher le filtre de sécurité. L'ajout d'une mention de style artistique (comme "digital illustration") peut réduire davantage les blocages liés au réalisme.
Le taux de réussite via APIYI (apiyi.com) est généralement supérieur à une connexion directe à l'API Google, car la plateforme optimise les paramètres de sécurité.
FAQ
Q1 : Pourquoi la même invite fonctionne-t-elle parfois et est-elle bloquée à d’autres moments ?
Parce que le second niveau de filtrage de sécurité analyse l'image générée, et non l'invite. Avec la même invite, les images générées par le modèle varient légèrement à chaque fois (en raison de la nature aléatoire des modèles de diffusion), et certains résultats peuvent accidentellement franchir le seuil du filtre de sécurité. C'est pourquoi réessayer la même invite peut parfois fonctionner : le modèle génère alors par hasard une image "plus sûre".
Q2 : Est-il normal que thoughtsTokenCount soit supérieur à 0 mais que candidatesTokenCount soit égal à 0 ?
Oui, c'est normal. Cela indique précisément que le blocage s'est produit au second niveau (côté sortie) : le modèle a terminé sa réflexion (Thinking) et a généré l'image, mais celle-ci a été interceptée par le filtre de sécurité juste avant la sortie finale. Les jetons de réflexion ont été consommés (173), mais comme aucune image n'a été réellement produite, le nombre de jetons de sortie est comptabilisé à 0. Il s'agit d'un mode de réponse spécifique à IMAGE_SAFETY, contrairement au blocage de premier niveau (où le thoughtsTokenCount est également à 0).
Q3 : Que faire si les images de lingerie ou de maillots de bain pour le e-commerce sont fréquemment bloquées ?
Il s'agit d'un scénario de faux positif fréquent et bien connu. On trouve de nombreux rapports sur les forums de développeurs Google concernant les "images de lingerie e-commerce non-NSFW avec une erreur IMAGE_SAFETY". Nos recommandations : 1) utilisez des photos de produits à plat (sans mannequin) plutôt que des photos avec mannequin ; 2) précisez dans votre invite "product flat lay, no model, white background" ; 3) passez par APIYI (apiyi.com), car les configurations des paramètres de sécurité de la plateforme sont optimisées pour les scénarios e-commerce.
Q4 : Les requêtes bloquées sont-elles facturées sur APIYI ?
Non. APIYI garantit qu'aucune facturation n'est appliquée en cas d'échec de génération, y compris pour les blocages IMAGE_SAFETY. Vous ne payez que pour les images générées avec succès. Cela correspond à la logique de facturation de l'API officielle de Google (les images bloquées ne sont pas facturées), mais APIYI va plus loin en vous assurant qu'aucun frais, même minime, lié aux jetons d'entrée ne sera prélevé.
Conclusion
Les points clés concernant l'erreur IMAGE_SAFETY de Nano Banana Pro :
- L'erreur est due au filtrage de sortie de second niveau : Votre invite a passé le premier niveau, le modèle a terminé sa réflexion (173 jetons) et l'image a été générée, mais elle a été bloquée lors de la sortie finale par un filtre de sécurité impossible à désactiver.
- Les blocages ne sont pratiquement jamais facturés :
candidatesTokenCount: 0signifie que les jetons de sortie ne sont pas comptabilisés. Google précise que "les images bloquées ne sont pas facturées", et l'utilisation via APIYI vous offre une garantie supplémentaire d'absence de frais en cas d'échec. - L'optimisation des invites peut augmenter le taux de réussite à 70-80 % : Le principe fondamental est "plus c'est précis, plus c'est sûr" — ajoutez des détails sur le contexte, le style artistique, la description vestimentaire et privilégiez les invites en anglais.
Nous vous recommandons d'invoquer Nano Banana Pro via APIYI (apiyi.com) pour bénéficier de configurations de sécurité optimisées, d'une absence de facturation en cas d'échec et d'une réduction de 28 %, afin de minimiser l'impact des faux positifs IMAGE_SAFETY sur votre activité.
📚 Références
-
Documentation des paramètres de sécurité de l'API Gemini : Explications officielles sur les paramètres de sécurité
- Lien :
ai.google.dev/gemini-api/docs/safety-settings - Description : Inclut la configuration BLOCK_NONE et la liste des catégories de sécurité
- Lien :
-
Guide complet de résolution IMAGE_SAFETY pour Nano Banana Pro : 8 méthodes pour améliorer le taux de réussite
- Lien :
help.apiyi.com/en/nano-banana-pro-image-safety-error-fix-guide-en.html - Description : Contient des modèles d'optimisation d'invites et des solutions par scénario
- Lien :
-
Discussion sur l'erreur IMAGE_SAFETY sur le forum des développeurs Google AI : Rapports de la communauté et réponses officielles
- Lien :
discuss.ai.google.dev/t/nano-banana-is-unusable-because-of-the-new-safety-filters/132366 - Description : Google reconnaît que les filtres sont "trop prudents"
- Lien :
-
Centre de documentation APIYI : Garantie de non-facturation en cas d'échec avec Nano Banana Pro
- Lien :
docs.apiyi.com - Description : Inclut l'optimisation des paramètres de sécurité et des guides de configuration pour les scénarios e-commerce
- Lien :
Auteur : Équipe technique APIYI
Échanges techniques : N'hésitez pas à en discuter dans les commentaires. Pour plus d'informations, consultez le centre de documentation APIYI sur docs.apiyi.com
