Muitos desenvolvedores, ao realizarem a primeira invocação do modelo da API Nano Banana Pro (correspondente ao modelo gemini-3-pro-image-preview do Google), caem na mesma armadilha: reutilizam o parâmetro size: "1024x1024" da era OpenAI / DALL-E. O resultado? Ou a resolução da imagem gerada não muda, ou ocorre um erro 400, ou o parâmetro é simplesmente ignorado pelo servidor.
Este é o "bug de alta frequência" mais comum ao chamar a API do Nano Banana Pro. O procedimento correto é: a resolução é determinada em conjunto pelos parâmetros imageConfig.imageSize (definição 1K/2K/4K) e imageConfig.aspectRatio (proporção de tela 1:1/16:9/…), não envie mais nenhum campo size. Este artigo explica tudo em 600 palavras e fornece códigos em curl, Python e Node.js prontos para copiar e executar.
Pontos principais da invocação da API Nano Banana Pro
Antes de colar o código, lembre-se de três regras de ouro — se você entender estas três, 90% do conteúdo deste artigo será apenas detalhe:
- Correspondência do nome do modelo: Nano Banana Pro =
gemini-3-pro-image-preview(também chamado de Gemini 3 Pro Image), pertencente à série de modelos de geração de imagens/edição do Google Gemini 3. Algumas pessoas no mercado o chamam de Nano Banana 2, mas essencialmente é a mesma coisa. - O protocolo é nativo do Gemini: Não é o protocolo compatível com OpenAI Chat Completions. O caminho da requisição é
:generateContent, os campos de nível superior do corpo da requisição sãocontents+generationConfig; não existemmessagesnem o camposizeno estilo OpenAI. - Resolução = imageSize × aspectRatio:
imageSizecontrola o nível de definição (512 / 1K / 2K / 4K), easpectRatiocontrola a proporção da imagem (1:1 / 16:9 / 9:16 / …). Ambos decidem juntos os pixels de saída finais.
📌 Resumo em uma frase: Ao usar o protocolo Gemini para chamar o Nano Banana Pro, esqueça completamente o hábito do
size: "1024x1024"da OpenAI. O endpoint do Nano Banana Pro na APIYI (apiyi.com) mantém integralmente o protocolo nativo do Gemini; qualquer sintaxe deimageConfigválida no Google oficial também funcionará na APIYI.
Visão geral dos parâmetros principais do Nano Banana Pro
| Parâmetro | Localização | Função | Exemplo de valor |
|---|---|---|---|
imageSize |
generationConfig.imageConfig |
Nível de definição | "512" / "1K" / "2K" / "4K" |
aspectRatio |
generationConfig.imageConfig |
Proporção de tela | "1:1" / "16:9" / "9:16" / "4:3" etc. |
responseModalities |
generationConfig |
Modalidade de saída | ["IMAGE"] (obrigatório) |
contents[].parts[].text |
contents |
comando de texto | Texto livre |
contents[].parts[].inline_data |
contents |
imagem de referência(base64) | Contém mime_type e data |
⚠️ O campo
sizenão está na tabela: Porque ele simplesmente não é um parâmetro válido do protocolo Gemini, não o envie.
Por que não adicionar o parâmetro size? Motivos da camada de protocolo
Esta é a seção mais importante deste artigo. Vamos explicar isso detalhadamente em três níveis.
Nível de protocolo: Gemini e OpenAI são dois conjuntos de especificações independentes
A API de imagem da OpenAI (DALL-E 2/3, gpt-image-1) utiliza o parâmetro de string de nível superior size: "1024x1024"; enquanto a API de imagem do Google Gemini 3 foi projetada com um objeto aninhado imageConfig. As duas especificações são independentes entre si. O Nano Banana Pro segue o protocolo nativo do Gemini, portanto:
- ❌
size: "1024x1024"—— O protocolo Gemini não possui este campo - ❌
size: "1K"—— Não possui este campo - ❌
n: 4—— Não possui o campo da OpenAI para "gerar N imagens de uma vez" - ✅
imageConfig.imageSize: "1K"—— Correto - ✅
imageConfig.aspectRatio: "16:9"—— Correto
Nível de comportamento: O que acontece se você enviar o size?
O processamento no lado do servidor geralmente ocorre de três formas, e nenhuma delas é o que você deseja:
- Ignorado silenciosamente: O gateway upstream descarta campos desconhecidos como inválidos; você acha que funcionou, mas na verdade a saída é o padrão 1K 1:1.
- Erro 400 direto: Gateways com validação de esquema rigorosa rejeitarão a solicitação imediatamente devido ao campo desconhecido.
- Afeta cobrança/roteamento: Algumas camadas de proxy podem interpretar o
sizecomo um sinal de roteamento e direcionar para a versão de endpoint incorreta.
Nível de engenharia: Dívida técnica e manutenção confusa
Muitas equipes encapsulam várias APIs, como OpenAI, Gemini e Stability, na mesma camada de chamada, acostumando-se a reutilizar um "campo size genérico". Isso parece elegante, mas é um terreno fértil para bugs. Sugerimos que, ao chamar interfaces nativas do Gemini, como o Nano Banana Pro, você crie um fluxo de conversão separado, mapeando explicitamente o size para imageConfig.imageSize + imageConfig.aspectRatio, em vez de apenas repassar o size original.
💡 Sugestão: Ao usar o APIYI (apiyi.com) para chamar o Nano Banana Pro, escreva uma pequena função de conversão de parâmetros que desmembre a string que sua equipe costuma usar, como
"1024x1024", emimageSize: "1K"+aspectRatio: "1:1", eliminando a mistura de parâmetros na origem.
Tabela comparativa completa de imageSize × aspectRatio
Níveis de imageSize e cobrança
| imageSize | Limite de resolução aproximado | Token de saída | Preço unitário (ref.) | Cenário recomendado |
|---|---|---|---|---|
"512" |
Nível 512×512 | Menor | Mais barato | Miniaturas / Rascunhos |
"1K" |
Nível 1024×1024 | ~1120 | ≈ $0,134 | Recomendação padrão |
"2K" |
Nível 2048×2048 | ~1120 | ≈ $0,134 | Pôsteres de alta definição |
"4K" |
Nível 4096×4096 | ~2000 | ≈ $0,24 (80% mais caro) | Qualidade de impressão |
💰 Dica de custo: O 4K é cerca de 80% mais caro que 1K/2K, não use 4K indiscriminadamente. Para a grande maioria dos cenários Web/App, 1K já é suficiente; use 4K apenas quando precisar de ultra-definição. Consulte os preços mais recentes no site oficial do APIYI (apiyi.com).
Lista completa de suporte para aspectRatio
| Proporção | Uso |
|---|---|
"1:1" |
Avatar / Imagem quadrada para redes sociais |
"16:9" |
Capa de vídeo horizontal / Papel de parede de desktop |
"9:16" |
Vídeo curto vertical / Papel de parede de celular |
"4:3" |
Proporção horizontal de foto tradicional |
"3:4" |
Proporção vertical de foto tradicional |
"3:2" / "2:3" |
Proporção padrão DSLR |
"4:5" / "5:4" |
Imagem única para Instagram |
"21:9" |
Cinema ultra-wide |
"1:4" / "4:1" |
Banner longo |
"1:8" / "8:1" |
Uso especial para formatos extremamente longos |
Mapeamento de combinações comuns → Pixels finais
| imageSize | aspectRatio | Pixels de saída aproximados |
|---|---|---|
1K |
1:1 |
1024 × 1024 |
1K |
16:9 |
1024 × 576 |
1K |
9:16 |
576 × 1024 |
2K |
1:1 |
2048 × 2048 |
2K |
16:9 |
2048 × 1152 |
4K |
1:1 |
4096 × 4096 |
4K |
9:16 |
2304 × 4096 |
4K |
21:9 |
4096 × 1728 |
Nota: Os pixels reais podem sofrer pequenos ajustes de ±N devido às regras de alinhamento interno do modelo, mas isso não afeta o nível de clareza visual.
Aqui estão os exemplos mínimos de execução para as três linguagens. Todos os exemplos realizam a mesma tarefa: enviam uma imagem original + um comando, e geram uma imagem em 1K com proporção 1:1.
Versão curl (mais direta, ideal para depuração)
curl -X POST \
"https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "Authorization: Bearer sua-chave-APIYI" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [
{
"inline_data": {
"mime_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAA...(base64 da imagem original)"
}
},
{
"text": "Transforme esta imagem em estilo cyberpunk, mantendo a pose do personagem"
}
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K"
}
}
}'
Versão Python (recomendamos usar requests diretamente, sem depender de SDKs)
import base64
import requests
with open("input.png", "rb") as f:
img_b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
headers={
"Authorization": "Bearer sua-chave-APIYI",
"Content-Type": "application/json",
},
json={
"contents": [{
"parts": [
{"inline_data": {"mime_type": "image/png", "data": img_b64}},
{"text": "Transforme esta imagem em estilo cyberpunk, mantendo a pose do personagem"},
]
}],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "1K",
},
},
},
timeout=120,
)
data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
f.write(base64.b64decode(out_b64))
Versão Node.js (use fetch nativo para evitar que o SDK remova o imageConfig)
import fs from "node:fs";
const imgB64 = fs.readFileSync("input.png").toString("base64");
const resp = await fetch(
"https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
{
method: "POST",
headers: {
"Authorization": "Bearer sua-chave-APIYI",
"Content-Type": "application/json",
},
body: JSON.stringify({
contents: [{
parts: [
{ inline_data: { mime_type: "image/png", data: imgB64 } },
{ text: "Transforme esta imagem em estilo cyberpunk, mantendo a pose do personagem" },
],
}],
generationConfig: {
responseModalities: ["IMAGE"],
imageConfig: {
aspectRatio: "1:1",
imageSize: "1K",
},
},
}),
},
);
const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));
🔧 Por que recomendamos fortemente usar
fetchourequestsnativos: É um problema conhecido que alguns SDKs (incluindo versões antigas do LiteLLM e certas versões do SDK do Google para Node) filtram oimageConfigcomo um campo desconhecido, fazendo com queimageSize/aspectRatiosejam ignorados. Construir o corpo da requisição JSON manualmente evita esse problema em 100% dos casos. Se você insistir em usar um SDK, certifique-se de estar na versão mais recente e verifique o corpo final da requisição em um interceptador ou via console.
Lista de verificação: 6 erros comuns na invocação
Problema 1: Incluir parâmetros de tamanho no estilo OpenAI
// ❌ Errado: size não é um campo válido no protocolo Gemini
{
"contents": [...],
"size": "1024x1024",
"generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}
// ✅ Correto: remova o size, mantenha apenas o imageConfig
{
"contents": [...],
"generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}
Problema 2: Nomes de campos com sublinhado (snake_case)
Os campos do imageConfig na interface do Gemini 3 usam camelCase: imageSize, aspectRatio, responseModalities. Erros comuns:
- ❌
image_size/aspect_ratio/response_modalities - ✅
imageSize/aspectRatio/responseModalities
Problema 3: imageConfig sendo removido pelo SDK
Como mencionado, algumas versões de SDK filtram campos desconhecidos. Como depurar:
- Imprima o corpo HTTP real antes e depois da chamada do SDK.
- Use
mitmproxyouCharlespara capturar a requisição real de saída. - Se o
imageConfigsumir, usefetchourequestsnativos.
Problema 4: Esquecer o responseModalities
// ❌ Sem definir responseModalities, pode retornar texto puro em vez de imagem
{ "generationConfig": { "imageConfig": {...} } }
// ✅ É obrigatório declarar explicitamente que a modalidade de retorno inclui IMAGE
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }
Problema 5: Não implementar backoff exponencial para erros 429
Quando a carga do servidor está saturada, ele retorna algo como:
{ "error": { "message": "Carga do servidor saturada, tente novamente mais tarde", "type": "upstream_error", "code": 429 } }
A prática correta é o backoff exponencial (3s → 6s → 12s). Não tente repetir imediatamente, pois isso só aumentará o congestionamento:
import time
for attempt in range(3):
resp = requests.post(url, json=body, headers=headers, timeout=120)
if resp.status_code != 429:
break
time.sleep(3 * (2 ** attempt)) # 3s, 6s, 12s
Problema 6: Colocar imagens de referência na posição errada
O Nano Banana Pro suporta múltiplas imagens (imagem original + várias imagens de referência). Todas devem ser itens inline_data dentro do array parts, com o comando de texto no final:
// ✅ Correto: imagens primeiro, texto depois
"parts": [
{ "inline_data": { "mime_type": "image/png", "data": "base64 da original" } },
{ "inline_data": { "mime_type": "image/png", "data": "base64 da ref 1" } },
{ "inline_data": { "mime_type": "image/png", "data": "base64 da ref 2" } },
{ "text": "Por favor, aplique o estilo da ref 1 na original e use a composição da ref 2" }
]
🧰 Resumo: Transforme estes 6 pontos em um "Checklist do Nano Banana Pro" interno. Revisá-lo antes de implementar uma nova chamada evitará mais de 90% dos bugs básicos. O endpoint do Nano Banana Pro na APIYI (apiyi.com) segue totalmente o protocolo Gemini, então todas essas dicas são universais.
Decomposição do fluxo de invocação do usuário: onde é mais provável ocorrer um erro
Muitos leitores postaram logs de invocação que são quase idênticos ao fluxo que você forneceu:
Frontend POST /api/generate
→ server.js extrai parâmetros
→ verifica modelKey.startsWith('nano-banana')
→ _generateViaGemini() monta o corpo da requisição
→ POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
→ retorna / tenta novamente
Vamos marcar, nó por nó, as etapas onde é mais fácil ocorrer um erro:
| Etapa | Problema comum | Sugestão |
|---|---|---|
| Parâmetros do frontend | Passar habitualmente size: "1024x1024" |
Divida em dois campos imageSize + aspectRatio e passe adiante |
| Montagem do body no server.js | Passar o campo size para o Gemini por engano | Delete explicitamente o size na função de montagem |
| Roteamento de modelo | Roteou nano-banana para 1.5 em vez de 3 Pro |
Escreva o nome do modelo exatamente como gemini-3-pro-image-preview |
| Envio da requisição | Usou versão do SDK com validação de esquema | Mude para fetch nativo ou atualize o SDK para a versão mais recente |
| Tratamento de erro | Lançar erro 429 diretamente para o usuário | Implemente uma estratégia de retentativa com recuo exponencial (3 vezes) |
| Parsing da resposta | Tentar ler como text, mas o resultado é IMAGE |
Caminho correto: candidates[0].content.parts[0].inline_data.data |
📋 Resumo: A estrutura do fluxo que você postou está correta. Basta remover aquele campo
sizeexcedente na etapa de "extração de parâmetros" e confirmar que oserver.jsnão o reinsira fora dogenerationConfig. Assim, toda a cadeia ficará limpa.
FAQ – Perguntas Frequentes
Q1: Nano Banana Pro e Nano Banana 2 são a mesma coisa?
Sim. Muitas pessoas na comunidade chamam o Gemini 3 Pro Image (gemini-3-pro-image-preview) de Nano Banana 2 / Nano Banana Pro; os três nomes referem-se ao mesmo modelo. No APIYI (apiyi.com), o nome do modelo correspondente deve seguir a documentação oficial.
Q2: O que acontece se eu não passar o imageConfig?
O modelo produzirá o resultado com base nos valores padrão internos (geralmente 1K + 1:1). Se você não se importa com a resolução, pode omitir; se tiver requisitos específicos de proporção, deve passar o imageConfig explicitamente.
Q3: Posso usar o protocolo Gemini e passar size como no OpenAI?
Não é recomendável fazer isso de forma confiável. O protocolo Gemini não possui um campo size, e misturar parâmetros só trará comportamentos imprevisíveis. Usar imageConfig.imageSize + imageConfig.aspectRatio é a forma mais segura.
Q4: Escolher 4K para imageSize garante uma qualidade de imagem melhor?
Os detalhes da imagem serão mais ricos, mas o custo é quase o dobro (~$0,24 vs $0,134) e o tempo de geração é maior. Para imagens de Web/App, 1K ou 2K geralmente são suficientes. Sugiro testar um conjunto de imagens reais do seu negócio e comparar visualmente antes de decidir.
Q5: Qual a diferença entre invocar o Nano Banana Pro via APIYI (apiyi.com) e chamar a API oficial do Google diretamente?
O APIYI oferece autenticação unificada no estilo OpenAI (Bearer Token) + entrada acessível no país + faturamento unificado, mantendo o protocolo de invocação exatamente no formato nativo do Gemini. Isso significa que imageConfig / aspectRatio / responseModalities que você vê na documentação oficial do Google são totalmente equivalentes no APIYI (apiyi.com).
Q6: Por que configurei imageSize: "2K" e a saída ainda é 1K?
Os 3 motivos mais comuns: (1) uso de um SDK que filtra campos desconhecidos, (2) nome do campo escrito como image_size, (3) nível de aninhamento do generationConfig incorreto. Capture o pacote de rede real primeiro para confirmar se o corpo está em conformidade com a especificação, depois verifique o servidor.
Q7: O que fazer com o limite de taxa (429) do upstream?
Implemente uma retentativa com recuo exponencial (3s/6s/12s). Se o seu negócio for sensível à latência, considere alternar entre diferentes grupos no seu workspace do APIYI (apiyi.com) ou solicitar uma cota independente. Nunca escreva um loop infinito de retentativa imediata, pois a estratégia de limitação de taxa continuará bloqueando você.
Q8: Existe um limite para a quantidade de imagens na entrada multimodal?
A interface do Gemini 3 image tem um limite para o tamanho total das imagens em uma única requisição (geralmente medido em MB, verifique a documentação oficial). Sugiro não exceder 4-5 imagens de referência e controlar o tamanho de cada uma (redimensione antes de converter para base64), caso contrário, você poderá disparar um erro 413 ou timeout.
Resumo: Grave o "método de dois parâmetros de resolução" na memória muscular
Se você só puder levar uma lição para casa, que seja esta:
A resolução de saída final do Nano Banana Pro =
imageConfig.imageSize×imageConfig.aspectRatio. Não envie mais nenhum camposizeno estilo OpenAI.
Checklist completo:
- ✅ Nome do modelo:
gemini-3-pro-image-preview - ✅ Endpoint:
/v1beta/models/.../generateContent - ✅
generationConfig.imageConfig.imageSize∈512/1K/2K/4K - ✅
generationConfig.imageConfig.aspectRatio∈1:1/16:9/9:16/4:3/3:4/21:9/ … - ✅
generationConfig.responseModalitiesdeve incluir"IMAGE" - ✅ Entradas com múltiplas imagens devem ser colocadas no array
parts, com o comando de texto por último - ✅ Para limites de taxa (429), utilize o recuo exponencial (3s/6s/12s)
- ❌ Não envie
size: "1024x1024" - ❌ Não escreva
image_size/aspect_ratio(o formato snake_case está incorreto) - ❌ Não confie em SDKs antigos que filtram campos desconhecidos; capture o tráfego de rede para confirmar
📢 Uma última observação: Se você está acessando o Nano Banana Pro através do APIYI (apiyi.com), basta copiar os modelos de código curl / Python / Node.js fornecidos neste artigo. Todos os parâmetros estão em estrita conformidade com o protocolo nativo do Gemini. É só copiar, colar, trocar a chave API e rodar.
Autor: Equipe APIYI · Organizando continuamente as melhores práticas de invocação de API de Modelos de Linguagem Grande · apiyi.com
