Como Usar a API Google Nano Banana 2: Guia Completo

Construir aplicações com geração de imagem por IA parece mágica — até você se deparar com a complexidade da documentação da API, dores de cabeça com autenticação e pesadelos de depuração. Você já viu o que o Nano Banana 2 pode fazer: imagens impressionantes geradas a partir de prompts de texto, saída de qualidade Pro em velocidades Flash, e recursos como consistência de assunto que tornam fluxos de trabalho multi-imagem possíveis. Mas, na verdade, integrá-lo ao seu código? É aí que a maioria dos desenvolvedores trava.

Você provavelmente já tentou se aprofundar na documentação do Google, juntar fluxos de autenticação e testar requisições manualmente em um CLI. Talvez você já tenha esgotado sua cota de API depurando requisições malformadas ou se perguntou por que suas imagens sempre voltam borradas. A verdade é que integrar qualquer nova API, especialmente uma tão poderosa quanto o Nano Banana 2, requer mais do que apenas ler a documentação. Você precisa de um fluxo de trabalho que permita testar rapidamente, iterar em prompts e gerenciar suas chamadas de API de forma eficiente.

Neste guia, vamos percorrer tudo o que você precisa para integrar o Nano Banana 2 em suas aplicações, desde a configuração do seu projeto Google Cloud até a escrita de código pronto para produção em Python e JavaScript. Mas eis o que torna este guia diferente: mostraremos como testar e depurar cada etapa usando o Apidog, para que você não esteja apenas copiando código, mas construindo um fluxo de trabalho que pode manter e escalar.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma conta do Google Cloud (ou inscreva-se em cloud.google.com)
• Compreensão básica de APIs REST
• Python 3.8+ ou Node.js 18+ instalados
• Um cliente de API como o Apidog para testes

Este guia assume que você está familiarizado com a realização de requisições HTTP e o tratamento de dados JSON. Se você é novo em APIs, confira nosso Guia Definitivo de Teste de API para os fundamentos.

Configurando seu Projeto Google Cloud

Para usar a API Nano Banana 2, você precisa de um projeto Google Cloud com a API Generative Language habilitada.

Passo 1: Criar um Novo Projeto

1. Vá para o Google Cloud Console
2. Clique em "Selecionar um projeto" → "Novo Projeto"
3. Insira um nome para o projeto (por exemplo, "geracao-imagens-nano-banana")
4. Clique em "Criar"
5. Aguarde a criação do projeto

Passo 2: Configurar Acesso à API

1. Vá para "APIs e Serviços" → "Credenciais"
2. Clique em "Criar Credenciais" → "Chave de API"
3. Copie sua chave de API (você precisará dela mais tarde)

Dica Pro:

Obtendo sua Chave de API

Existem duas maneiras de obter acesso à API:

Opção 1: Google Cloud Console (Recomendado para Produção)

Siga os passos acima — a chave de API que você criou é sua credencial de acesso.

Opção 2: Google AI Studio (Recomendado para Desenvolvimento)

1. Vá para Google AI Studio
2. Faça login com sua conta Google
3. Clique em "Obter Chave de API" na navegação
4. Clique em "Criar Chave de API" (ou selecione um projeto existente)
5. Copie sua chave de API

A chave do AI Studio é ótima para desenvolvimento e testes. Para produção, use a chave do Google Cloud Console para melhor gerenciamento e segurança.

Sua Primeira Requisição de API

Vamos fazer uma requisição simples de geração de imagem para verificar se tudo funciona.

Usando cURL

curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp-image-generation:predict?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cute banana character wearing sunglasses, fun cartoon style",
    "number_of_images": 1
  }'

Compreendendo a Resposta

{
  "predictions": [
    {
      "image": {
        "mimeType": "image/png",
        "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      },
      "generatedImageId": "img_abc123xyz",
      "metadata": {
        "prompt": "A cute banana character wearing sunglasses, fun cartoon style",
        "seed": 12345,
        "finishReason": "SUCCESS"
      }
    }
  ],
  "metadata": {
    "modelVersion": "gemini-3.1-flash-image-preview",
    "processingTimeMs": 1250,
    "contentAuthenticity": {
      "synthID": "enabled",
      "c2pa": "enabled"
    }
  }
}

O campo data contém uma imagem PNG codificada em base64. Você precisará decodificá-la para salvar ou exibir a imagem.

Integração Python

Veja como integrar o Nano Banana 2 em suas aplicações Python:

Instalando a Biblioteca Cliente

pip install google-generativeai

Geração Básica de Imagens

import google.generativeai as genai
import base64
import os

# Configure the API with your key
genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))

# Create the model
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Generate an image
response = model.generate_images(
    prompt="A modern minimalist office with natural lighting, indoor plants, standing desk, 4k quality",
    number_of_images=1
)

# Save the image
if response.generated_images:
    image_data = response.generated_images[0].image_bytes
    with open("output_image.png", "wb") as f:
        f.write(image_data)
    print("Image saved to output_image.png")

Geração Avançada de Imagens com Parâmetros

import google.generativeai as genai
from PIL import Image
import io

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))

model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Generate with advanced parameters
response = model.generate_images(
    prompt="A futuristic cityscape at night with neon lights, flying cars, cyberpunk aesthetic",
    number_of_images=1,
    aspect_ratio="16:9",
    negative_prompt="blurry, low quality, distorted, ugly",
    safety_filter_level="block_medium_and_above"
)

# Process the response
for idx, generated_image in enumerate(response.generated_images):
    # Convert to PIL Image
    image = Image.open(io.BytesIO(generated_image.image_bytes))

    # Save with custom name
    image.save(f"generated_image_{idx}.png")

    # Access metadata
    print(f"Image {idx}: {generated_image.finish_reason}")
    print(f"Seed: {generated_image.seed}")

Geração de Imagens em Lote

import google.generativeai as genai
import os

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Generate multiple images at once
prompts = [
    "A red sports car on a mountain road",
    "A cozy coffee shop interior",
    "A minimalist bedroom design",
    "A tropical beach sunset"
]

# Generate all images
for idx, prompt in enumerate(prompts):
    response = model.generate_images(
        prompt=prompt,
        number_of_images=1,
        aspect_ratio="16:9"
    )

    if response.generated_images:
        image_data = response.generated_images[0].image_bytes
        with open(f"image_{idx + 1}.png", "wb") as f:
            f.write(image_data)
        print(f"Generated: image_{idx + 1}.png")

Exemplo de Consistência de Personagem

import google.generativeai as genai

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Base character description
base_character = "A friendly cartoon robot with round body, blue eyes, antenna on head, white and light blue color scheme"

# Generate base character (note the seed for consistency)
response1 = model.generate_images(
    prompt=base_character + ", front view, standing pose",
    number_of_images=1,
    seed=42  # Important: note this seed
)

base_seed = response1.generated_images[0].seed
print(f"Base character seed: {base_seed}")

# Generate variations using the same seed
poses = [
    "sitting pose",
    "waving hand",
    "holding a ball",
    "walking"
]

for pose in poses:
    response = model.generate_images(
        prompt=f"{base_character}, {pose}, same character as seed {base_seed}",
        number_of_images=1,
        seed=base_seed  # Same seed maintains consistency
    )

    if response.generated_images:
        filename = f"robot_{pose.replace(' ', '_')}.png"
        with open(filename, "wb") as f:
            f.write(response.generated_images[0].image_bytes)
        print(f"Generated: {filename}")

Integração JavaScript/Node.js

Instalando a Biblioteca Cliente

npm install @google/generative-ai

Geração Básica de Imagens

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");
const path = require("path");

// Initialize with API key
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function generateImage() {
  // Get the model
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  // Generate image
  const result = await model.generateImages({
    prompt: "A beautiful sunset over the ocean with palm trees silhouette",
    numberOfImages: 1,
  });

  // Process the response
  if (result.generatedImages && result.generatedImages.length > 0) {
    const imageData = result.generatedImages[0].imageBytes;

    // Save to file
    fs.writeFileSync("sunset.png", Buffer.from(imageData, "base64"));
    console.log("Image saved to sunset.png");

    // Log metadata
    console.log("Seed:", result.generatedImages[0].seed);
    console.log("Finish Reason:", result.generatedImages[0].finishReason);
  }
}

generateImage().catch(console.error);

Tratando Respostas Base64

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function generateAndProcessImage() {
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  const result = await model.generateImages({
    prompt: "Professional headshot of a person in business attire, studio lighting",
    numberOfImages: 1,
    aspectRatio: "1:1",
    resolution: "1024x1024"
  });

  const generatedImage = result.generatedImages[0];

  // Decode base64
  const imageBuffer = Buffer.from(generatedImage.imageBytes, "base64");

  // Save with metadata in filename
  const filename = `portrait_${generatedImage.seed}.png`;
  fs.writeFileSync(filename, imageBuffer);

  return {
    filename,
    seed: generatedImage.seed,
    finishReason: generatedImage.finishReason
  };
}

generateAndProcessImage()
  .then(info => console.log("Generated:", info))
  .catch(err => console.error("Error:", err));

Exemplo de API REST com Express.js

const express = require("express");
const { GoogleGenerativeAI } = require("@google/generative-ai");
const multer = require("multer");
const fs = require("fs");

const app = express();
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

app.use(express.json());

// Image generation endpoint
app.post("/api/generate", async (req, res) => {
  try {
    const { prompt, aspect_ratio, negative_prompt, number_of_images } = req.body;

    const model = genAI.getGenerativeModel({
      model: "gemini-2.0-flash-exp-image-generation",
    });

    const result = await model.generateImages({
      prompt,
      numberOfImages: number_of_images || 1,
      aspectRatio: aspect_ratio || "1:1",
      negativePrompt: negative_prompt
    });

    // Convert images to base64 for response
    const images = result.generatedImages.map((img, idx) => ({
      id: idx,
      seed: img.seed,
      finishReason: img.finishReason,
      data: img.imageBytes // Base64 encoded
    }));

    res.json({
      success: true,
      images,
      metadata: {
        modelVersion: result.response?.metadata?.modelVersion,
        processingTimeMs: result.response?.metadata?.processingTimeMs
      }
    });
  } catch (error) {
    console.error("Generation error:", error);
    res.status(500).json({
      success: false,
      error: error.message
    });
  }
});

// Batch generation endpoint
app.post("/api/generate/batch", async (req, res) => {
  try {
    const { prompts } = req.body;
    const model = genAI.getGenerativeModel({
      model: "gemini-3.1-flash-image-preview",
    });

    const results = [];

    for (const prompt of prompts) {
      const result = await model.generateImages({
        prompt,
        numberOfImages: 1
      });

      results.push({
        prompt,
        seed: result.generatedImages[0]?.seed,
        success: !!result.generatedImages[0]
      });
    }

    res.json({ success: true, results });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Parâmetros Avançados

O Nano Banana 2 suporta vários parâmetros para ajustar a geração de suas imagens:

Referência de Parâmetros

Opções de Resolução

# Available resolutions
resolutions = [
    "512x512",    # Thumbnail, social media
    "768x768",    # Small web images
    "1024x1024",  # Standard square
    "1024x768",   # 4:3 landscape
    "1280x720",   # HD ready
    "1920x1080",  # Full HD
    "2048x2048",  # High quality
    "3840x2160"   # 4K
]

# Using specific resolution
response = model.generate_images(
    prompt="Professional product photography of a watch",
    resolution="2048x2048"
)

Proporções de Tela

aspect_ratios = [
    "1:1",    # Square (Instagram posts)
    "4:3",    # Standard photo
    "16:9",   # Landscape (YouTube, web)
    "9:16",   # Portrait (Stories, TikTok)
    "21:9",   # Ultrawide
    "3:4",    # Portrait standard
    "2:3"     # Portrait photo
]

# Using specific aspect ratio
response = model.generate_images(
    prompt="Modern office interior design",
    aspect_ratio="16:9"
)

Tratando Respostas

Analisando a Estrutura da Resposta

import google.generativeai as genai

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

response = model.generate_images(
    prompt="A fantasy castle on a mountain",
    number_of_images=2
)

# Access predictions (generated images)
for idx, image in enumerate(response.generated_images):
    print(f"Image {idx + 1}:")
    print(f"  - Seed: {image.seed}")
    print(f"  - Finish Reason: {image.finish_reason}")
    print(f"  - Image Bytes Length: {len(image.image_bytes)}")

# Access metadata
print("\nMetadata:")
print(f"  - Model Version: {response.response.metadata.model_version}")
print(f"  - Processing Time: {response.response.metadata.processing_time_ms}ms")
print(f"  - SynthID: {response.response.metadata.content_authenticity.synth_id}")

Convertendo para Diferentes Formatos

from PIL import Image
import io
import base64

def image_to_different_formats(image_bytes):
    """Convert generated image to multiple formats."""
    # Load as PIL Image
    img = Image.open(io.BytesIO(image_bytes))

    # Save as PNG
    img.save("image.png", "PNG")

    # Save as JPEG (with quality)
    img.save("image.jpg", "JPEG", quality=95)

    # Convert to WebP (smaller file size)
    img.save("image.webp", "WEBP", quality=85)

    # Get base64 for embedding
    buffered = io.BytesIO()
    img.save(buffered, format="PNG")
    base64_str = base64.b64encode(buffered.getvalue()).decode()

    return base64_str

Tratamento de Erros

O tratamento adequado de erros é essencial para aplicações em produção:

Tratamento de Erros em Python

import google.generativeai as genai
from google.api_core.exceptions import (
    ResourceExhausted,
    InvalidArgument,
    ServiceUnavailable
)

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

def generate_image_with_retry(prompt, max_retries=3):
    """Generate image with retry logic."""

    for attempt in range(max_retries):
        try:
            response = model.generate_images(
                prompt=prompt,
                number_of_images=1
            )
            return response

        except ResourceExhausted as e:
            # Rate limit or quota exceeded
            print(f"Rate limited (attempt {attempt + 1}/{max_retries})")
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise Exception("Rate limit exceeded. Please try again later.")

        except InvalidArgument as e:
            # Invalid prompt or parameters
            raise ValueError(f"Invalid request: {e}")

        except ServiceUnavailable as e:
            # Service temporarily unavailable
            print(f"Service unavailable (attempt {attempt + 1}/{max_retries})")
            if attempt < max_retries - 1:
                import time
                time.sleep(5)  # Wait 5 seconds
            else:
                raise Exception("Service unavailable. Please try again later.")

    return None

# Usage
try:
    result = generate_image_with_retry("A beautiful landscape")
    if result:
        print("Image generated successfully")
except Exception as e:
    print(f"Error: {e}")

Tratamento de Erros em JavaScript

const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function generateImageWithRetry(prompt, maxRetries = 3) {
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await model.generateImages({
        prompt,
        numberOfImages: 1
      });
      return result;
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error.message);

      if (error.message.includes("RESOURCE_EXHAUSTED")) {
        // Rate limited
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else if (error.message.includes("INVALID_ARGUMENT")) {
        // Invalid prompt
        throw new Error(`Invalid prompt: ${error.message}`);
      } else if (attempt === maxRetries - 1) {
        throw error;
      }
    }
  }

  return null;
}

// Usage
generateImageWithRetry("A serene mountain lake at sunrise")
  .then(result => {
    if (result) {
      console.log("Image generated successfully");
    }
  })
  .catch(err => {
    console.error("Failed to generate image:", err.message);
  });

Códigos de Erro Comuns

Testando com Apidog

Apidog é uma excelente ferramenta para testar e depurar sua integração da API Nano Banana 2:

Configurando seu Workspace Apidog

1. Abra o Apidog e crie um novo projeto
2. Adicione variáveis de ambiente:

GEMINI_API_KEY: sua_chave_de_api_aqui
BASE_URL: https://generativelanguage.googleapis.com/v1beta

Criando Requisições de API

Endpoint: POST /models/gemini-3.1-flash-image-preview:predict

Headers:

Authorization: Bearer {{GEMINI_API_KEY}}
Content-Type: application/json

Corpo da Requisição:

{
  "prompt": "{{prompt}}",
  "number_of_images": 1,
  "aspect_ratio": "1:1"
}

Parâmetros de Consulta:

key: {{GEMINI_API_KEY}}

Escrevendo Scripts de Teste

// Test: Successful generation
pm.test("Image generation successful", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.predictions).to.have.property('image');
    pm.expect(jsonData.predictions[0].metadata.finishReason).to.eql('SUCCESS');
});

// Test: Response contains metadata
pm.test("Response has required metadata", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.metadata).to.have.property('modelVersion');
    pm.expect(jsonData.metadata).to.have.property('processingTimeMs');
});

// Test: Content authenticity verified
pm.test("Content authenticity enabled", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.metadata.contentAuthenticity.synthID).to.eql('enabled');
});

// Test: Response time acceptable
pm.test("Response time under 5 seconds", function() {
    pm.expect(pm.response.responseTime).to.be.below(5000);
});

Criando uma Coleção para Teste em Lote

Salve essas requisições no Apidog para construir uma coleção de testes:

1. Geração Básica - Geração de imagem única
2. Geração em Lote - Múltiplos prompts
3. Consistência de Personagem - Teste da mesma semente
4. Tratamento de Erros - Teste de prompt inválido
5. Teste de Performance - Múltiplas requisições concorrentes

Melhores Práticas de Produção

Ao implantar o Nano Banana 2 em produção:

1. Proteja sua Chave de API

# Never hardcode API keys
# Use environment variables
import os

API_KEY = os.environ.get("GEMINI_API_KEY")

# Or use a secrets manager
# AWS Secrets Manager, HashiCorp Vault, etc.

2. Implemente Cache

import hashlib
import redis

redis_client = redis.Redis(host='localhost', port=6379, db=0)

def generate_image_cached(prompt, seed=None):
    """Generate image with caching."""
    # Create cache key from prompt + seed
    cache_key = f"image:{hashlib.md5(f'{prompt}:{seed}'.encode()).hexdigest()}"

    # Check cache
    cached = redis_client.get(cache_key)
    if cached:
        return cached

    # Generate new image
    response = model.generate_images(prompt=prompt, seed=seed)
    image_data = response.generated_images[0].image_bytes

    # Cache for 24 hours
    redis_client.setex(cache_key, 86400, image_data)

    return image_data

3. Limitação de Taxa (Rate Limiting)

from flask import Flask, request, jsonify
from flask_limiter import Limiter

app = Flask(__name__)
limiter = Limiter(app, key_func=lambda: request.headers.get("X-API-Key"))

@app.route("/generate", methods=["POST"])
@limiter.limit("10 per minute")  # Adjust based on your quota
def generate():
    # Your generation logic
    pass

4. Monitoramento e Registro (Logging)

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def generate_with_logging(prompt):
    logger.info(f"Generating image for prompt: {prompt[:50]}...")

    start_time = time.time()
    try:
        response = model.generate_images(prompt=prompt)
        elapsed = time.time() - start_time

        logger.info(f"Generated successfully in {elapsed:.2f}s")
        return response

    except Exception as e:
        elapsed = time.time() - start_time
        logger.error(f"Failed after {elapsed:.2f}s: {e}")
        raise

5. Webhook para Processamento Assíncrono

Para grandes trabalhos em lote, use webhooks:

# Request with webhook
response = model.generate_images(
    prompt="Generate 10 product images",
    number_of_images=10,
    webhook_url="https://your-server.com/webhook/nano-banana"
)

# Your webhook handler
@app.route("/webhook/nano-banana", methods=["POST"])
def handle_webhook():
    data = request.json

    if data["status"] == "completed":
        images = data["images"]
        # Process completed images
    elif data["status"] == "failed":
        # Handle failure
        pass

    return jsonify({"received": True})

Conclusão

A API Nano Banana 2 oferece uma maneira poderosa de integrar a geração de imagens por IA em suas aplicações. Com suporte a várias linguagens de programação, parâmetros flexíveis e tratamento robusto de erros, você pode construir desde geradores de imagem simples até fluxos de trabalho de produção complexos.

Pontos chave:

• Começar requer um projeto Google Cloud e uma chave de API
• Os SDKs de Python e JavaScript tornam a integração direta
• Parâmetros avançados como sementes e prompts negativos oferecem controle preciso
• Apidog ajuda a testar e depurar sua integração de API
• Implantações em produção precisam de segurança, cache, limitação de taxa e monitoramento

Comece com os exemplos básicos neste guia, depois adicione progressivamente recursos avançados à medida que se sentir mais confortável com a API.

Próximo Passo: