mattmuller/gemini-reference-images

Génération d'images Gemini avec images de référence

Gemini peut générer une image à partir des images que vous fournissez, et non uniquement à partir d'un prompt. C'est ainsi que vous gardez un personnage cohérent dans une série, ou que vous affichez une capture d'écran réelle dans une scène générée au lieu d'une scène inventée.

Limites par modèle

Tirées de la documentation de l'API Gemini Image Generation datée du 19 septembre 2026. Les noms et limites des modèles changent ; relisez la page actuelle avant de vous y fier.

Jusqu'à 14 images de référence au total, avec des sous-limites par catégorie qui sont des allocations séparées plutôt qu'un pool partagé :

Modèle	objets	personnages	style
gemini-3.1-flash-image	10	4	3
gemini-3-pro-image	6	5	-
gemini-3.1-flash-lite-image	14	-	-

Les captures d'écran de produits et les portraits de personnages ne sont donc pas en concurrence pour le budget. Une même image peut contenir plusieurs écrans et plusieurs personnes.

Les catégories sont inférées, non déclarées. Via l'AI SDK et une passerelle, vous envoyez des parties file indifférenciées ; aucun champ ne dit « celle-ci est un personnage ». Traitez 14 comme le plafond réel et restez bien en dessous. Les limites par catégorie décrivent ce que le modèle peut faire, pas ce que vous pouvez affirmer. En pratique, deux écrans et deux personnes suffisent largement.

L'appel

Via la passerelle Vercel AI Gateway, le modèle d'image s'est comporté comme un modèle de langage : il a répondu à l'API textuelle avec l'image dans files, et l'API image dédiée l'a rejeté. Vérifiez comment votre propre fournisseur expose la route.

const result = await generateText({
  model,
  prompt: [{ role: 'user', content: [
    ...references.map((r) => ({ type: 'file', mediaType: r.mediaType, data: r.bytes })),
    { type: 'text', text: prompt },        // images d'abord, puis l'instruction
  ]}],
  providerOptions: { google: {
    responseModalities: ['IMAGE'],
    imageConfig: { aspectRatio: '4:5', imageSize: '2K' },
  }},
});
const file = result.files.find((f) => f.mediaType.startsWith('image/'));

Rapports d'aspect : 1:1 3:2 2:3 3:4 4:3 4:5 5:4 9:16 16:9 21:9. Tailles : 512px 1K 2K 4K.

Pièges

1. N'écrivez pas « pas de filigrane » lorsque des références sont attachées. Gemini semble interpréter cela comme une demande de suppression des filigranes des images fournies et refuse tout l'appel. Mesuré en septembre 2026, deux exécutions par fin de prompt, deux références attachées :

Fin du prompt	Résultat
« Jamais une illustration, un rendu 3D... »	image, image
« Les personnes, les visages, les mains... sont les bienvenus. »	image, image
« Aucun logo d'une autre entreprise. »	image, image
« Pas de filigranes. »	content-filter, content-filter

Seul le terme « filigrane » a fait échouer. Une convention de prompt négatif copiée d'un autre outil d'image (dont beaucoup se terminent par watermark, over-saturated, stock-image) peut silencieusement casser chaque appel.

2. Un refus ressemble à un modèle capricieux. Il a renvoyé finishReason: 'content-filter', zéro fichier et une chaîne vide. Si votre message d'erreur imprime result.text, vous ne voyez rien et concluez que l'API n'est pas fiable. Consignez toujours finishReason.

3. Réessayez une réponse vide avant de lever une exception. Le modèle ne renvoie parfois rien pour des raisons normales. Ne levez l'exception qu'après épuisement des tentatives, et incluez finishReason dans l'erreur.

4. Ne décrivez pas ce qui se trouve sur un écran fourni. La capture d'écran est déjà là ; décrire son contenu entre en conflit avec l'image et produit un hybride. Décrivez uniquement la scène qui l'entoure : la table, la lumière, les mains.

5. Le modèle redessine ; il ne colle pas. Les petits textes sur un écran de référence peuvent revenir légèrement déformés, avec des noms et des étiquettes plausibles mais incorrects. Cela est acceptable en taille vignette, mais erroné pour tout ce qu'un lecteur zoomera. Vérifiez la sortie plutôt que de supposer la fidélité.

6. Les références ne rendent pas la sortie moins synthétique. Une image construite à partir d'une capture d'écran réelle et d'un portrait réel est toujours générée par IA. Appliquez les règles d'étiquetage ou de divulgation qui régissent votre utilisation des images générées ; vérifiez ce qui s'applique à vous plutôt que de supposer que les références vous en exemptent.

Checklist pour un pipeline d'images de référence

• Les parties de référence viennent avant la partie texte.
• Moins de 14 références ; idéalement 4 ou moins.
• Le prompt décrit la scène, pas le contenu des écrans fournis.
• Aucun terme de filigrane dans le prompt.
• finishReason est consigné et les résultats vides sont réessayés.
• La sortie est inspectée pour les petits textes déformés avant publication.