|

Solução completa para o erro Unsupported file URI type no Nano Banana Pro: 5 causas principais e solução definitiva

ByAPIYI - Stable and affordable AI API

Recentemente, um cliente ao realizar a invocação do modelo Nano Banana Pro (ID do modelo: gemini-3-pro-image-preview) para imagem para imagem, encontrou um erro 400 com um estilo bem "Google":

{
  "status_code": 400,
  "error": {
    "message": "Unsupported file URI type: {{ $json.imageUrls }}. File URI must be a File API (e.g. https://generativelanguage.googleapis.com/files/<id>), Youtube (e.g. https://www.youtube.com/watch?v=<id>), or HTTPS (e.g. http://path/to/file).), or a valid gURI (e.g. gs://bucket/object",
    "type": "",
    "code": 400
  }
}

Esta mensagem de erro do Nano Banana Pro na verdade já aponta o "culpado": Unsupported file URI type: {{ $json.imageUrls }}. Note que {{ $json.imageUrls }} é a variável de template do n8n que não foi substituída — ou seja, o cliente escreveu uma expressão dinâmica no fluxo de trabalho, mas essa expressão não foi renderizada pelo motor como uma URL real, sendo inserida literalmente como uma string no campo fileUri da API do Gemini. O Google, naturalmente, não consegue identificar uma URI que parece um {{ ... }}, e rejeita a requisição imediatamente.

Com base neste erro real e nos requisitos da documentação oficial do Google para o gemini-3-pro-image-preview sobre formatos de entrada, este artigo detalha 5 cenários de gatilho comuns e fornece o código de reprodução mínima e a solução de correção imediata para cada um. Após a leitura, você será capaz de localizar e corrigir qualquer requisição falha com o erro Unsupported file URI type em menos de 5 minutos.

nano-banana-pro-unsupported-file-uri-type-error-fix-pt-pt 图示

Visão geral das informações principais do erro do Nano Banana Pro

Antes de colocar a mão na massa, vamos consolidar as informações cruciais deste erro e os formatos de URI permitidos oficialmente em uma tabela.

Dimensão Fato principal
ID do modelo gemini-3-pro-image-preview (nome oficial do Nano Banana Pro na API do Gemini)
Status HTTP do erro 400 (Bad Request, erro de parâmetro do cliente)
Campo chave do erro Unsupported file URI type
Local real do problema Campo fileData.fileUri no corpo da requisição
Literal que aparece no erro {{ $json.imageUrls }} (expressão n8n não renderizada)
Tipos de URI aceitos pelo Gemini URI da File API / URL do YouTube / URL HTTPS pública / URI GCS gs://
Formatos de imagem aceitos pelo Gemini JPEG, JPG, PNG, WEBP, HEIF
Nano Banana Pro suporta URL externa? ✅ Sim (Modelos Gemini 2.5+ suportam nativamente HTTPS público / URL pré-assinada)
Causa raiz provável Variável de template de fluxos de trabalho low-code (n8n / Make / Zapier) não substituída

🎯 Dica de diagnóstico rápido: Se o seu cliente não quiser compartilhar o corpo completo da requisição, peça para ele realizar uma chamada bem-sucedida no console da APIYI (apiyi.com) usando o mesmo modelo gemini-3-pro-image-preview + a mesma imagem de referência, e depois compare o corpo da requisição falha com a bem-sucedida. Esta é a maneira mais rápida de identificar o erro do Nano Banana Pro.

title: "5 causas principais do erro 'Unsupported file URI type' no Nano Banana Pro"
description: "Descubra as 5 causas mais comuns para o erro 'Unsupported file URI type' no Nano Banana Pro e como resolvê-las rapidamente."

5 causas principais do erro "Unsupported file URI type" no Nano Banana Pro

Após categorizar todos os casos reais, o erro Unsupported file URI type pode ser resumido em 5 causas típicas. Vamos listá-las por "frequência de ocorrência", da maior para a menor.

Causa 1: Variáveis de modelo no n8n / Make / Zapier não foram renderizadas

Este é o principal suspeito para este erro específico. {{ $json.imageUrls }} é a sintaxe de expressão do n8n e, em condições normais, deveria ser substituída pelo URL real gerado pelo nó anterior antes da execução, por exemplo: https://cdn.example.com/uploads/abc.jpg. No entanto, existem algumas situações típicas onde essa substituição falha:

  1. O campo Body do nó HTTP Request não está no modo "Expression", mas sim no modo "Fixed", fazendo com que todo o JSON seja enviado como uma string de texto puro;
  2. O corpo JSON utiliza aspas duplas aninhadas, fazendo com que o n8n interprete erroneamente a expressão como parte do conteúdo da string, ignorando a renderização;
  3. A estrutura de saída do nó anterior não corresponde ao caminho que você escreveu — por exemplo, o nó anterior gera imageUrl (singular), mas você escreveu $json.imageUrls (plural). Após a falha na análise, o n8n retorna a expressão original;
  4. A expressão em um sub-nó não itera de acordo com o Item, mas fixa no primeiro registro, resultando em undefined em certas entradas, que ao ser serializado como string, torna-se o texto original.

Como diagnosticar: Se você vir {{ ... }} na mensagem de erro do Gemini, é 100% de certeza que se trata deste problema, pois um URL real nunca teria esse formato.

Causa 2: Erro de digitação no nome do campo, resultando em undefined / null

Logo em seguida, temos problemas com nomes de campos. É muito provável que o código do cliente apresente esta situação:

// O campo retornado pela API upstream é imageUrl (singular)
const upstream = { imageUrl: "https://cdn.example.com/a.jpg" };

// Mas o downstream escreveu imageUrls (plural, com s)
fileUri: upstream.imageUrls   // O resultado é undefined

Quando undefined é serializado em JSON ou concatenado em uma string, ele se torna a string "undefined". O Gemini também não consegue reconhecê-la e lança um erro 400 quase idêntico ao de uma variável de modelo não renderizada. A diferença é que o literal que aparece no erro é undefined em vez de {{ ... }}.

Causa 3: Passar um array como se fosse uma string para o fileUri

A terceira causa ocorre frequentemente em cenários de "processamento em lote de várias imagens". O campo fileData.fileUri da API do Gemini aceita apenas uma string única, não um array. Muitos desenvolvedores cometem este erro:

// ❌ Erro: inserir um array diretamente no fileUri
{
  "fileData": {
    "fileUri": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"],
    "mimeType": "image/jpeg"
  }
}

Após a serialização JSON, este campo fileUri torna-se uma string ["https://...", "https://..."]. O Gemini falha ao analisar e retorna diretamente o erro Unsupported file URI type. A forma correta é gerar um elemento parts independente para cada imagem, em vez de colocar o array dentro de um único fileUri.

Causa 4: Protocolo de URL ou formato de caminho não suportado

O quarto tipo de problema refere-se a "desvios de formato". A API do Gemini aceita apenas 4 tipos de URI; qualquer formato fora desse escopo disparará o mesmo erro:

Tipo de URI Exemplo Aceito pelo gemini-3-pro-image-preview
Caminho File API https://generativelanguage.googleapis.com/files/abc123 ✅
URL do YouTube https://www.youtube.com/watch?v=xxxxx ✅ (usado principalmente para compreensão de vídeo)
URL HTTPS pública https://cdn.example.com/img.jpg ✅ (suporte nativo a partir do Gemini 2.5+)
URI GCS gs:// gs://my-bucket/img.jpg ✅ (caminho Vertex AI)
http:// simples http://cdn.example.com/img.jpg ⚠️ Recusado em alguns casos, recomenda-se atualizar para HTTPS
Caminho local file:// file:///Users/me/a.jpg ❌
data:image/...;base64, dataURL base64 ❌ (deve ser colocado em inlineData)
URL S3 pré-assinada https://bucket.s3.amazonaws.com/...?X-Amz-... ✅
URL SAS Azure https://account.blob.core.windows.net/...?sv=... ✅

Se você inserir um caminho de arquivo local, um base64 começando com data: ou um URL de rede privada interna no fileUri, você disparará invariavelmente o erro do Nano Banana Pro.

Causa 5: URL acessível, mas requer autenticação / não retorna uma imagem

A última categoria é "o URL parece correto, mas o Gemini não consegue obter o conteúdo". Situações comuns:

  • Links privados de OSS / Qiniu / Cloudinary sem permissão pública, fazendo com que o Gemini receba um erro 403;
  • O URL de assinatura temporária expirou;
  • O URL não retorna uma imagem, mas uma página HTML (por exemplo, a "página de compartilhamento" de um serviço de hospedagem de imagens, em vez do link direto);
  • O URL redireciona para uma página de login;
  • O tipo MIME não corresponde ao campo mimeType.

Esses problemas às vezes também são lançados como Unsupported file URI type, ou podem se transformar em um erro 400 Invalid or unsupported file uri. A solução para ambos é a mesma: acesse o URL diretamente em uma janela anônima do navegador para verificar se é possível baixar uma imagem válida. Este é o método mais simples e eficaz.

nano-banana-pro-unsupported-file-uri-type-error-fix-pt-pt 图示

Mínima reprodução e solução definitiva para o erro do Nano Banana Pro

Após analisar as 5 causas principais, apresento abaixo o código de reprodução mínima + a versão corrigida para cada cenário. Você pode copiar e substituir diretamente no seu fluxo de trabalho ou backend.

Correção 1: Passagem correta do parâmetro imageUrls no n8n

Para o cliente que está enfrentando o erro do Nano Banana Pro, se ele estiver usando o nó HTTP Request do n8n, a sintaxe correta deve ser esta:

Configuração do nó HTTP Request:

  • Method: POST
  • URL: https://api.apiyi.com/v1/messages (substitua pelo seu endereço de serviço proxy de API da APIYI)
  • Authentication: Header Auth (insira sua chave API)
  • Body Content Type: JSON
  • Specify Body: Selecione Using JSON (em vez de Using Fields)
  • JSON Body (atenção: o JSON completo deve estar em modo de expressão, ou seja, o botão roxo "fx" à esquerda deve estar ativado):
={
  "model": "gemini-3-pro-image-preview",
  "contents": [
    {
      "parts": [
        { "text": "Transforme esta imagem no estilo de Hayao Miyazaki" },
        {
          "fileData": {
            "fileUri": "{{ $json.imageUrls }}",
            "mimeType": "image/jpeg"
          }
        }
      ]
    }
  ]
}

Existem 3 pontos cruciais:

  1. A string JSON deve começar com o sinal =, informando ao n8n que todo o bloco é uma expressão que precisa ser processada;
  2. "{{ $json.imageUrls }}" deve estar entre aspas duplas externas para que o {{ }} interno seja substituído pelo valor real da string;
  3. O nó anterior deve obrigatoriamente gerar um campo chamado imageUrls; se ele gerar imageUrl (singular) ou image_url, ajuste o nome do campo adequadamente.

Ao atender a esses 3 pontos, o erro Unsupported file URI type desaparecerá imediatamente.

Correção 2: Prevenção de erros de digitação em Python / Node.js

Se o cliente estiver usando código backend, recomendo adicionar uma validação de entrada para detectar erros de digitação antes de enviar a solicitação ao Gemini:

import requests

def call_nano_banana_pro(prompt: str, image_url: str):
    # Validação defensiva: bloqueia None / strings vazias / strings de template antes do envio
    if not image_url or not isinstance(image_url, str):
        raise ValueError(f"image_url deve ser uma string não vazia, valor atual: {image_url!r}")
    if image_url.startswith("{{") or "undefined" in image_url:
        raise ValueError(f"image_url parece ser uma variável de template não renderizada: {image_url}")
    if not image_url.startswith(("https://", "gs://")):
        raise ValueError(f"image_url deve começar com https:// ou gs://: {image_url}")

    payload = {
        "model": "gemini-3-pro-image-preview",
        "contents": [{
            "parts": [
                {"text": prompt},
                {"fileData": {
                    "fileUri": image_url,
                    "mimeType": "image/jpeg"
                }}
            ]
        }]
    }

    resp = requests.post(
        "https://api.apiyi.com/v1/messages",
        headers={"Authorization": "Bearer SUA_CHAVE_API"},
        json=payload,
        timeout=120
    )
    return resp.json()

Essa abordagem de "validar antes de enviar" intercepta 90% dos erros do Nano Banana Pro antes da invocação do modelo, evitando poluir os logs de erro do lado do Gemini.

Correção 3: Divisão correta de múltiplas imagens em partes (parts)

Se você realmente precisa enviar várias imagens de referência para o Nano Banana Pro (por exemplo, para transferência de estilo + fixação de personagem), a maneira correta é criar elementos parts independentes para cada imagem, em vez de inserir um array no fileUri:

// ✅ Forma correta
const imageUrls = [
  "https://cdn.example.com/style.jpg",
  "https://cdn.example.com/person.jpg"
];

const payload = {
  model: "gemini-3-pro-image-preview",
  contents: [{
    parts: [
      { text: "Desenhe o personagem da segunda imagem no estilo da primeira" },
      ...imageUrls.map(url => ({
        fileData: { fileUri: url, mimeType: "image/jpeg" }
      }))
    ]
  }]
};

const resp = await fetch("https://api.apiyi.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer SUA_CHAVE_API"
  },
  body: JSON.stringify(payload)
});

Essa estrutura não apenas evita o Unsupported file URI type, mas também ajuda o Gemini a entender corretamente a relação semântica entre as imagens.

Correção 4: Fallback para base64 inline em URLs inacessíveis

Se a URL que você obteve for de um bucket privado, rede interna ou uma URL temporária, o servidor do Gemini pode não conseguir acessá-la. A alternativa mais segura é usar inlineData + base64:

import base64
import requests

def call_with_base64(prompt: str, local_path: str):
    with open(local_path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode("utf-8")

    payload = {
        "model": "gemini-3-pro-image-preview",
        "contents": [{
            "parts": [
                {"text": prompt},
                {"inlineData": {
                    "mimeType": "image/jpeg",
                    "data": b64
                }}
            ]
        }]
    }

    return requests.post(
        "https://api.apiyi.com/v1/messages",
        headers={"Authorization": "Bearer SUA_CHAVE_API"},
        json=payload
    ).json()

Nota: inlineData utiliza o campo data (base64 puro, sem o prefixo data:image/jpeg;base64,), enquanto fileData utiliza o campo fileUri. Ambos são mutuamente exclusivos, não preencha os dois ao mesmo tempo.

🎯 Dica de estabilidade: Para cenários onde a origem da URL é incontrolável (como uploads de clientes ou APIs de terceiros), recomendamos que a geração de imagem para imagem utilize base64 inline por padrão + a invocação do gemini-3-pro-image-preview através de um serviço proxy de API como o apiyi.com, evitando que o Gemini recuse URLs externas devido a problemas de rede ou permissões.

Lista de verificação para solução de problemas do Nano Banana Pro

Resumimos todo o conteúdo acima em uma lista de "verificação de 5 minutos". Quando o cliente encontrar o erro Unsupported file URI type, basta seguir estes passos:

Lista de verificação de 5 minutos

Passo Ação Resultado esperado
1 Copie o valor literal após Unsupported file URI type: na mensagem de erro Obter o valor real de fileUri recebido pelo Gemini
2 Verifique se o valor contém {{, undefined, null ou [ Se sim → 90% de chance de ser template não renderizado ou erro no nome do campo
3 Abra a URL diretamente em uma janela anônima do navegador Esperado: conseguir baixar uma imagem JPEG/PNG/WEBP válida
4 Verifique se o protocolo da URL é https:// ou gs:// Se não → altere o protocolo ou use base64
5 Verifique se é um bucket privado, assinatura expirada ou redirecionamento Se sim → use uma URL pública ou altere para base64
6 Tente reproduzir no painel da APIYI apiyi.com usando o mesmo modelo + uma imagem pública conhecida Se funcionar → o problema está no cliente; se falhar → reporte para nós

Seguindo esses 6 passos, praticamente não haverá erro do Nano Banana Pro cuja causa raiz não possa ser identificada.

Nano Banana Pro: FAQ sobre o erro "Unsupported file URI type"

Q1: Por que a mensagem de erro exibe literalmente {{ $json.imageUrls }}?

Isso acontece porque, ao receber a solicitação, a API do Gemini retorna o valor do campo fileUri exatamente como o recebeu. Esse é o comportamento padrão do Google para ajudar você a identificar rapidamente: "O que exatamente eu enviei?". Se você vir um literal como {{ ... }}, é 100% certeza de que a variável de modelo do seu fluxo de trabalho low-code não foi renderizada. Se vir undefined ou null, é um erro de digitação no nome do campo. Sugiro testar primeiro com uma URL pública fixa no APIYI (apiyi.com) para garantir que a chamada funcione e, em seguida, alinhar o corpo da requisição do seu cliente com esse modelo funcional.

Q2: Quais URLs são suportadas pelo Nano Banana Pro / gemini-3-pro-image-preview?

De acordo com a documentação oficial do Google, o fileUri aceita 4 tipos de URI: Caminhos da File API (https://generativelanguage.googleapis.com/files/...), URLs do YouTube (usadas principalmente para compreensão de vídeo), URLs HTTPS públicas (incluindo S3 Pre-signed e Azure SAS) e URIs GCS gs://. Como os modelos Gemini 2.5 e superiores suportam nativamente HTTPS público, o gemini-3-pro-image-preview não exige que você faça o upload da imagem para a File API antes da invocação.

Q3: O que fazer se {{ $json.imageUrls }} não for renderizado no n8n?

Existem 3 pontos de verificação comuns: Primeiro, o JSON Body do nó HTTP Request deve estar com o modo de expressão ativado (o sinal de = antes do JSON ou o botão "fx" à esquerda deve estar aceso); Segundo, o caminho do campo deve corresponder exatamente à saída real do nó anterior (você pode verificar o painel de saída após "Execute Node" no n8n para confirmar o nome do campo); Terceiro, se você estiver usando um sub-nó, a expressão por padrão pega apenas o primeiro item. Use o nó principal ou utilize o nó "Item Lists" para expandir os dados primeiro.

Q4: Como corrigir o erro quando aparece undefined?

Isso indica que você tentou acessar um campo inexistente no seu código. A correção mais rápida é adicionar uma asserção antes de chamar o Gemini: assert image_url is not None and isinstance(image_url, str). Em seguida, verifique o retorno da API upstream para confirmar o nome correto do campo. Erros de digitação comuns incluem imageUrls vs imageUrl, image_url vs imageUrl ou url vs uri. Em produção, recomendo usar o código Python da "Correção 2" deste artigo para bloquear strings que não sejam https ou gs antes mesmo de enviar a requisição.

Q5: Posso colocar várias imagens diretamente no fileUri?

Não. O fileUri aceita apenas uma única string. Se precisar enviar várias imagens, a forma correta é criar um novo elemento { "fileData": { "fileUri": "...", "mimeType": "..." } } para cada imagem e colocá-los todos no mesmo array parts. Assim, o Gemini conseguirá identificar corretamente a relação semântica entre as imagens.

Q6: O que fazer se eu não puder tornar públicas as URLs de buckets privados ou assinaturas temporárias?

A solução mais robusta é usar inlineData + base64: leia a imagem no seu lado, codifique-a em base64 e insira-a diretamente no corpo da requisição. Isso evita que o servidor do Gemini precise buscar recursos externos, contornando problemas de "falha de autenticação / assinatura expirada / MIME incompatível". O custo é que o corpo da requisição ficará maior, sendo ideal para cenários de imagem única e tamanho reduzido. Se você estiver realizando geração de imagens em alta concorrência, ainda recomendamos fazer o upload da imagem para uma CDN acessível publicamente e, em seguida, chamar o gemini-3-pro-image-preview via APIYI (apiyi.com). Isso evita o aumento de volume do base64 e facilita o cache e as tentativas de reenvio na camada da plataforma.

nano-banana-pro-unsupported-file-uri-type-error-fix-pt-pt 图示

Resumo: Melhores práticas após a correção do erro no Nano Banana Pro

Voltando ao erro específico do Nano Banana Pro: Unsupported file URI type: {{ $json.imageUrls }}, podemos afirmar com certeza — não é um problema do Gemini, mas sim do n8n / fluxo de trabalho low-code que não substituiu a variável de modelo pela URL real, fazendo com que o literal {{ ... }} fosse enviado exatamente como estava para a API do Gemini. A solução foi apresentada na "Correção 1": basta ativar o modo de expressão no JSON Body do nó HTTP Request e confirmar que o nó anterior realmente exportou o campo imageUrls.

Em um nível mais amplo, o erro Unsupported file URI type expõe um problema comum: muitas equipes carecem de uma camada de "validação de entrada" ao chamar APIs de imagem, o que faz com que, quando o Gemini recusa a solicitação, seja impossível distinguir se o problema é do modelo, da rede ou dos parâmetros. A lista de verificação de 5 minutos, o código de validação em Python e a sintaxe de expressão do n8n fornecidos aqui podem ser adotados como padrão pela sua equipe.

🎯 Recomendação final: Se você está criando um fluxo de trabalho de imagem para imagem baseado no gemini-3-pro-image-preview para seus clientes, sugerimos centralizar todas as chamadas do Nano Banana Pro em uma plataforma de serviço proxy de API como o APIYI (apiyi.com). Isso permite reproduzir rapidamente erros no console, comparar requisições falhas e alternar perfeitamente para modelos equivalentes como o Nano Banana 2 / Seedream em caso de falhas do próprio Google, garantindo que erros de parâmetro como o Unsupported file URI type sejam localizados e corrigidos imediatamente.

Autor: Equipe APIYI ｜ Focada na implementação e estabilidade de Modelos de Linguagem Grandes de IA. Para mais práticas de Gemini e APIs de imagem, visite APIYI em apiyi.com.

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts