mattmuller/gemini-reference-images

Geração de imagem no Gemini com imagens de referência

O Gemini pode gerar uma imagem a partir de imagens fornecidas por você, não apenas a partir de um prompt. É assim que você mantém um personagem consistente em um conjunto, ou renderiza uma captura de tela de um produto real dentro de uma cena gerada em vez de uma inventada.

Limites por modelo

Extraído da documentação de geração de imagem da API Gemini em 19 de setembro de 2026. Nomes de modelo e limites mudam; releia a página atual antes de confiar neles.

Até 14 imagens de referência no total, com sub-limites por categoria que são alocações separadas, não um pool compartilhado:

Modelo	objetos	personagens	estilo
gemini-3.1-flash-image	10	4	3
gemini-3-pro-image	6	5	-
gemini-3.1-flash-lite-image	14	-	-

Capturas de tela de produto e retratos de personagens, portanto, não competem pelo orçamento. Uma imagem pode conter várias telas e várias pessoas.

As categorias são inferidas, não declaradas. Por meio do AI SDK e de um gateway, você envia partes de file indiferenciadas; nenhum campo diz "esta é um personagem". Trate 14 como o teto real e fique bem abaixo dele. Os limites de categoria descrevem o que o modelo pode fazer, não algo que você possa afirmar. Na prática, duas telas mais duas pessoas são suficientes.

A chamada

Através do Vercel AI Gateway, o modelo de imagem se comportou como um modelo de linguagem: ele respondeu à API de texto com a imagem em files, e a API de imagem dedicada a rejeitou. Verifique como seu próprio provedor de rota a expõe.

const result = await generateText({
  model,
  prompt: [{ role: 'user', content: [
    ...references.map((r) => ({ type: 'file', mediaType: r.mediaType, data: r.bytes })),
    { type: 'text', text: prompt },        // imagens primeiro, depois a instrução
  ]}],
  providerOptions: { google: {
    responseModalities: ['IMAGE'],
    imageConfig: { aspectRatio: '4:5', imageSize: '2K' },
  }},
});
const file = result.files.find((f) => f.mediaType.startsWith('image/'));

Proporções de aspecto: 1:1 3:2 2:3 3:4 4:3 4:5 5:4 9:16 16:9 21:9. Tamanhos: 512px 1K 2K 4K.

Armadilhas

1. Não escreva "sem marcas d'água" quando referências estiverem anexadas. O Gemini parece interpretar isso como uma solicitação para remover marcas d'água das imagens fornecidas e recusa toda a chamada. Medido em setembro de 2026, duas execuções por cauda de prompt, duas referências anexadas:

Cauda do prompt	Resultado
"Nunca uma ilustração, um render 3D..."	imagem, imagem
"Pessoas, rostos, mãos... são todos bem-vindos."	imagem, imagem
"Nenhum logotipo de outra empresa."	imagem, imagem
"Sem marcas d'água."	filtro de conteúdo, filtro de conteúdo

Apenas a redação sobre marca d'água a acionou. Uma convenção de prompt negativo copiada de outra ferramenta de imagem (muitas terminam com marca d'água, supersaturado, imagem de banco de imagens) pode silenciosamente quebrar todas as chamadas.

2. Uma recusa parece um modelo instável. Ele retornou finishReason: 'content-filter', zero arquivos e uma string vazia. Se sua mensagem de erro imprimir result.text, você não vê nada e conclui que a API não é confiável. Sempre registre finishReason.

3. Repita uma resposta vazia antes de lançar uma exceção. O modelo ocasionalmente não retorna nada por motivos comuns. Lance a exceção somente após as tentativas se esgotarem e coloque finishReason no erro.

4. Não descreva o que está em uma tela fornecida. A captura de tela já está lá; palavras sobre seu conteúdo entram em conflito com a imagem e produzem um híbrido. Descreva apenas a cena que a contém: a mesa, a luz, as mãos.

5. O modelo redesenha; ele não cola. Texto pequeno em uma tela de referência pode voltar sutilmente distorcido, com nomes e rótulos plausíveis, mas incorretos. Isso é aceitável em tamanho de miniatura e errado para qualquer coisa que um leitor ampliará. Verifique a saída em vez de presumir fidelidade.

6. Referências não tornam a saída menos sintética. Uma imagem construída a partir de uma captura de tela real e um retrato real ainda é gerada por IA. Aplique quaisquer regras de rotulagem ou divulgação que governem seu uso de imagens geradas; verifique o que se aplica a você em vez de presumir que as referências isentam.

Checklist para um pipeline de imagens de referência

• As partes de referência vêm antes da parte de texto.
• Menos de 14 referências; idealmente 4 ou menos.
• O prompt descreve a cena, não o conteúdo das telas fornecidas.
• Sem redação sobre marca d'água no prompt.
• finishReason é registrado e resultados vazios são repetidos.
• A saída é inspecionada quanto a texto pequeno distorcido antes da publicação.