Guia de referência do Gemini Nano Banana para desenvolvedores JavaScript

Todos os Geminis, todas as bananas. As imagens generativas entraram em uma nova era com o novo modelo Nano Banana do Google. O avanço dos sofisticados modelos de linguagem de grande escala (LLMs) abriu novas fronteiras no desenvolvimento de aplicações, especialmente no campo da IA multimodal.

A capacidade de processar e gerar conteúdo em diferentes tipos de dados, como texto e imagens. Na vanguarda dessa inovação está o modelo Gemini Nano Banana (oficialmente chamado de gemini-2.5-flash-image), uma ferramenta poderosa, otimizada para manipulação, geração e processamento rápidos de imagens de alta qualidade. Para desenvolvedores JavaScript e TypeScript, aproveitar esse potencial exige um conjunto de boas práticas específicas para garantir eficiência, facilidade de manutenção e segurança. Sim, segurança também!

Este artigo apresenta técnicas práticas, rápidas e simples para integrar o Gemini Nano Banana às suas aplicações web modernas. Usamos ferramentas consolidadas, como o AI SDK, para oferecer uma camada de abstração com segurança de tipos sobre a complexidade da API subjacente, permitindo que você se concentre apenas na lógica da aplicação. Essa abstração é essencial para elevar a qualidade do código e preparar seus recursos de IA para o futuro.

No contexto do JavaScript, o principal uso do Gemini Nano Banana costuma envolver a geração e edição dinâmica de imagens, como criar composições fotorrealistas ou imagens estilizadas a partir de conteúdo enviado por usuários. Para isso, abordamos práticas operacionais essenciais: desde buscar imagens externas na web e convertê-las com eficiência para o formato Uint8Array, compatível com o modelo, até converter a saída binária bruta do modelo em um Data URL, por exemplo, para renderização no cliente.

Além disso, exploramos estratégias avançadas de engenharia de prompts, especialmente a técnica de intercalar texto descritivo e imagens no array do prompt. Esse método fornece o contexto detalhado necessário para que o modelo execute tarefas complexas de composição, transformando solicitações vagas em resultados previsíveis e de alta qualidade.

Por fim, reconhecendo o papel da IA nos fluxos de trabalho de desenvolvimento, destacamos a importância de fornecer documentação relevante como base para plataformas de programação agentiva e de integrar verificações de segurança com ferramentas como o Snyk Studio. Assim, a velocidade de programação não compromete a segurança da aplicação.

Vamos ao guia de referência e às práticas de desenvolvimento com o Nano Banana para ajudar você a começar e melhorar o desempenho.

1. Use o AI SDK 

O AI SDK oferece uma estrutura poderosa, flexível e com segurança de tipos para desenvolvedores JavaScript e TypeScript que querem criar aplicações de IA sofisticadas.

Você pode usar as bibliotecas fornecidas por OpenAI, Google e outros, mas também vale a pena contar com uma camada de abstração sobre as APIs dos modelos.

Com uma API unificada e declarativa, o SDK abstrai as complexidades de interagir diretamente com modelos como o Gemini Nano Banana (chamado aqui de gemini-2.5-flash-image), permitindo que você se concentre na lógica da aplicação, em vez de gerenciar APIs em baixo nível.

Isso não só agiliza o processo de desenvolvimento, como também garante mais qualidade e facilidade de manutenção do código, especialmente em um ambiente TypeScript, no qual a tipagem forte reduz significativamente os erros em tempo de execução e melhora a experiência de desenvolvimento.

Veja a seguir um exemplo de uso do AI SDK com o modelo Gemini 2.5 Flash Image do Google (conhecido como Nano Banana):

import { generateText } from 'ai'
import { createGoogleGenerativeAI } from '@ai-sdk/google'

const yodaImagePath = join(process.cwd(), 'data', 'yoda.jpg')
const yodaImageBuffer = await readFile(yodaImagePath)
const yodaImageUint8Array = new Uint8Array(yodaImageBuffer)

// Use AI SDK with generateText for Gemini 2.5 Flash Image (Nano Banana)
// This model supports image editing/generation with input images
const googleProvider = createGoogleGenerativeAI({ apiKey: apiKey })

const result = await generateText({
      model: googleProvider('gemini-2.5-flash-image'),
      prompt: [
        {
          role: 'user',
          content: [
            {
              type: 'text',
              text: 'Generate a realistic selfie photo of the person in the first image together with Yoda from Star Wars (shown in the second image). The person joins Yoda in the scene where he is at and hugs him in selfie style while they are both smiling and looking at the camera. The image should look natural and photorealistic, as if taken with a smartphone camera.'
            },
     {
              type: 'image',
              image: userImageUint8Array,
              mediaType: imageFile.type || 'image/jpeg'
            },
            {
              type: 'image',
              image: yodaImageUint8Array,
              mediaType: 'image/jpeg'
            }
         ]
        }
      ]
    })  

2. Extraia os resultados do modelo Nano Banana como Data URL

Depois de gerar uma imagem com sucesso usando um modelo multimodal como o Gemini Nano Banana (gemini-2.5-flash-image), o resultado geralmente é um arquivo de imagem bruto, muitas vezes armazenado em um buffer Uint8Array.

Para exibir essa imagem imediatamente em uma aplicação frontend executada no cliente, como um site criado com React, Vue ou JavaScript puro, é preciso converter os dados binários brutos para um formato que o navegador consiga interpretar nativamente.

O formato Data URL é a maneira mais direta e eficiente de fazer isso: ele incorpora os dados da imagem codificados em base64 diretamente no atributo src de uma tag <img>, permitindo que o resultado gerado seja renderizado instantaneamente para o usuário final, sem precisar de um endpoint separado no servidor nem salvar o arquivo em disco.

try {
   // Call the model with await generateText({})
   // ...

   // Extract the generated image from result.files
    const generatedImageFile = result.files?.find(file => file.mediaType?.startsWith('image/'))

    if (!generatedImageFile) {
      console.error('=== Error: No image file found ===')
      console.error('Available files:', result.files)
      console.error('Result text content:', result.text)
      throw new Error('No image was generated in the response')
    }

    // Convert Uint8Array to base64 data URL for the frontend
    const base64String = Buffer.from(generatedImageFile.uint8Array).toString('base64')
    const dataUrl = `data:${generatedImageFile.mediaType};base64,${base64String}`

    return {
      success: true,
      image: dataUrl
    }
  } catch (error: any) {
    console.error('Error generating selfie:', error)
    throw createError({
      statusCode: error.statusCode || 500,
      message: error.message || 'Failed to generate selfie'
    })
  }

3. Busque dados de imagens na web

Em vez de carregar o arquivo de imagem do sistema de arquivos local, você também pode buscá-lo em tempo real por uma URL remota e converter a resposta para o formato Uint8Array, compatível com a API do modelo.

Em aplicações JavaScript modernas, especialmente as executadas em um navegador, é comum trabalhar com recursos remotos. Em vez de se limitar a carregar o arquivo de imagem do sistema de arquivos local — algo que pode ser restringido por políticas de segurança ou simplesmente não ser viável para conteúdo web dinâmico —, você também pode buscar a imagem em tempo real por uma URL remota. Isso oferece mais flexibilidade e permite que o modelo processe imagens hospedadas em redes de distribuição de conteúdo (CDNs) ou servidores externos.

Para tornar esses dados remotos compatíveis com a API do modelo no dispositivo, que geralmente espera uma estrutura de dados específica, como Uint8Array, é preciso fazer uma conversão. O procedimento padrão é usar a API fetch para buscar o recurso, obter a resposta bruta e, em seguida, convertê-la para o formato Uint8Array necessário.

    // Fetch Yoda image
    const yodaResponse = await fetch('https://example.com/image.jpg')
    if (!yodaResponse.ok) {
      throw new Error('Failed to fetch Yoda image')
    }
    const yodaArrayBuffer = await yodaResponse.arrayBuffer()
    const yodaImageUint8Array = new Uint8Array(yodaArrayBuffer)

Esse processo garante que os dados binários da imagem, seja ela JPEG, PNG ou outro formato compatível, sejam representados corretamente como um array de inteiros sem sinal de 8 bits, que é o formato de entrada esperado pelas funções de processamento do modelo. Essa integração fluida entre a busca de dados remotos e a conversão de formatos é essencial para criar aplicações JavaScript robustas e dinâmicas, com inteligência no dispositivo.

4. Intercale texto descritivo para criar prompts detalhados

A API do modelo e a API generateText({}) não permitem anotar cada imagem para explicar o que ela representa. Assim, se você especificar vários arquivos, a ordem fica implícita e pode confundir o modelo, especialmente se o prompt for ambíguo.

Para contornar isso e obter melhores resultados com o prompt, você pode estruturá-lo como uma sequência de mensagens de chat e intercalar descrições em texto antes e depois das imagens. Assim, o modelo recebe mais contexto para interpretar o que você quer.

Veja a seguir como intercalar texto no prompt do modelo:

const result = await generateText({
      model: googleProvider('gemini-2.5-flash-image'),
      prompt: [
        {
          role: 'user',
          content: [
            {
              type: 'text',
              text: 'COMPOSITION INSTRUCTIONS: Generate a single, hyper-realistic, high-detail selfie photograph. The foundational scene and background must be derived exclusively from the Yoda background image (shown below); this setting serves as the environment for the final image.'
            },
            {
              type: 'text',
              text: '[Yoda Background Image]'
            },
            {
              type: 'image',
              image: yodaImageUint8Array,
              mediaType: 'image/jpeg'
            },
            {
              type: 'text',
              text: 'Integrate the person from the user selfie image (shown below) into the Yoda background, placing them standing close to Yoda. The final image should have a selfie-style perspective (close-up, intimate framing) as if taken from a first-person viewpoint, but DO NOT include any visible hands, smartphones, or camera equipment in the frame. The image should appear as if the camera is invisible, capturing a natural moment without showing the device or hand holding it.'
            },
            {
              type: 'text',
              text: '[User Selfie Image]'
            },
            {
              type: 'image',
              image: userImageUint8Array,
              mediaType: imageFile.type || 'image/jpeg'
            },
            {
              type: 'text',
              text: 'Both individuals must be smiling, looking directly into the lens, and their precise facial likenesses, clothing, and details from tyouheir respective input images must be accurately and seamlessly preserved. Maintain consistent, warm, soft, natural daylight and ensure the overall vibe is joyful and spontaneous. The final image must appear as a spontaneous, single-shot photograph taken in the original environment of the Yoda background image. IMPORTANT: Do not include any visible hands, smartphones, phones, or camera equipment in the final image - only show the people and background.'
            }
          ]
        }
      ]
    })

Essa técnica de intercalar texto e mídia no array content do prompt é uma maneira poderosa de ter controle detalhado sobre modelos multimodais, como o Gemini Nano Banana.

Ao tratar o prompt como uma conversa estruturada ou narrativa, você vai além de simples entradas de texto e imagem e viabiliza tarefas complexas, como preenchimento preciso de áreas, edição de composição e geração baseada em elementos visuais específicos. Com isso, a API de geração de imagens produz resultados mais previsíveis e de maior qualidade.

5. Use as regras do modelo para o desenvolvimento com IA

Se você trabalha com Gemini CLI, Claude Code, Cursor ou outras plataformas de programação agentiva, provavelmente quer fornecer contexto e documentação da API como base para que elas tenham um desempenho melhor e não alucinem chamadas de métodos inexistentes. Manter a documentação atualizada também ajuda a garantir que a assistência de programação com LLM use as versões mais recentes da API que você escolher.

Neste exemplo, vamos usar as regras do Cursor e o seguinte formato para o nome do arquivo: .cursor/rules/ai-sdk-google-provider-docs.mdc. Em seguida, crie o seguinte conteúdo:

---
alwaysApply: false
description: AI SDK API documentation for the Google Gemini LLM provider
globs: server/api/generate-selfie.post.ts
---

# Google Generative AI Provider

The [Google Generative AI](https://ai.google.dev) provider contains language and embedding model support for
the [Google Generative AI](https://ai.google.dev/api/rest) APIs.

// ...
// REST OF THE CONTENT
// ...

Basta copiar o conteúdo da documentação oficial, como a documentação do AI SDK em https://v6.ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai#gemini-25-models, ou de qualquer outra documentação de API para fornecer ao modelo um contexto atualizado.

6. Programe com vibe e segurança usando Snyk Studio

Infelizmente, muitos desenvolvedores que programam no vibe e usam programação agentiva para gerar código com IA só percebem tarde demais que trocaram a velocidade de programação por práticas de programação segura e outras responsabilidades de segurança de aplicações.

Exemplos do mundo real incluem segredos vazados e vulnerabilidades SSRF, que podem ser evitados ao equipar o agente de programação com inteligência de segurança.

O Snyk Studio se integra perfeitamente ao fluxo de programação agentiva, equipando o agente com verificações de segurança de aplicações integradas ao fluxo nativo de execução por meio de servidores MCP (Model Context Protocol), hooks e regras para agentes, entre outros mecanismos.

O Snyk Studio é gratuito e oferece instalação com um clique para Cursor, GitHub Copilot e Windsurf, além de integração com muitos outros agentes de programação, incluindo o marketplace do Cline e o Factory AI.

Quer saber mais sobre vibe coding? Confira nosso workshop sob demanda, “Como proteger o vibe coding: enfrentando os desafios de segurança do código gerado por IA.”