Nano Banana Pro 에서 'Unsupported file URI type' 또는 'Invalid or unsupported file uri'가 떠도, 먼저 prompt 부터 고치지 마세요. 대부분은 모델이 이미지를 이해하지 못하는 문제가 아니라, 이미지가 Gemini 로 올바른 파일 경로를 통해 도착하지 못한 문제입니다.
먼저 나눠야 하는 것은 두 가지입니다. 무엇을 보냈는가. 그리고 어느 Gemini surface 가 그것을 거절했는가. native Gemini file_data, OpenAI 호환 image_url, Vertex 의 gs://, 공개 HTTPS URL, 로컬 파일 경로는 같은 URI 규칙으로 움직이지 않습니다.
30초 분기표
이 오류에서 가장 먼저 할 일은 surface 와 입력 타입을 먼저 나누는 것입니다. 2026년 4월 9일 기준으로 Gemini 공식 문서를 다시 확인해도, native Gemini 는 Files API / files.register, OpenAI 호환은 image_url, Vertex 는 별도 object route 라는 구분은 그대로입니다.
| 무엇을 보냈나 | 가장 흔한 문제 | 가장 안전한 첫 행동 | 같은 path 에서 어떻게 확인하나 | 언제 다음 층으로 올라가나 |
|---|---|---|---|---|
| 공개 HTTPS URL | 웹에서 보이는 주소를 native Gemini file resource 와 혼동했다 | Gemini 쪽에서 먼저 upload 하거나, 실제 source 가 GCS object 면 그 object 를 등록한다 | 같은 Gemini 요청이 파일을 받아들인다 | 반환된 file resource 도 계속 실패한다 |
data:image/...;base64,... | surface 를 잘못 골랐거나 base64 가 중간에서 깨졌다 | OpenAI 호환 image_url 형태를 유지하고 clean payload 를 다시 만든다 | 같은 호환 요청이 이미지를 받아들인다 | clean payload 도 실패한다 |
gs://bucket/object | native Gemini 와 Vertex 를 섞었다 | Gemini 에서는 files.register, Vertex 에서는 gs:// 를 유지한다 | 같은 surface 가 object 를 받아들인다 | docs 에 맞춘 cloud route 도 실패한다 |
/tmp/a.png, file:///... 같은 local path | 기기 경로를 재사용 가능한 file URI 처럼 보냈다 | 먼저 upload 하고 반환된 resource 를 쓴다 | 같은 flow 가 valid resource 로 동작한다 | upload 뒤에도 실패하거나 wrapper 가 요청을 바꾼다 |
여기서 꼭 분리해야 하는 것이 하나 더 있습니다. 지원되는 이미지 형식이라고 해서 file route 까지 올바르다는 뜻은 아닙니다. Gemini current docs 는 PNG, JPEG, WEBP, HEIC, HEIF 를 지원하지만, 이 페이지의 오류는 그보다 앞단에서 나는 경우가 많습니다.
native Gemini file_data 를 쓰는 경우
native Gemini 가 원하는 것은 Gemini 가 이해할 수 있는 file resource 입니다. public URL 이나 local path 를 그대로 file_uri 로 넣으면, native Gemini 는 그걸 현재 resource 로 인정하지 않습니다.
현재 Files API docs는 흐름을 분명하게 설명합니다. 먼저 upload 하고, 반환된 file.uri 를 다음 request 에서 다시 씁니다. source file 이 Google Cloud Storage 에 있다면, 현재 Files API reference는 files.register 도 문서화합니다. 즉 public URL 을 이미 준비된 file resource 로 착각하지 말고, GCS object 를 Gemini 측 resource 로 바꾸는 공식 경로가 있다는 뜻입니다.
이 때문에 오래된 forum 답변은 지금도 방향은 맞지만 publish-layer truth 로는 부족할 수 있습니다. 여전히 “AI Studio / Gemini 는 GCS 를 못 쓰고, gs:// 는 Vertex 용”이라는 식의 말을 볼 수 있습니다. 그 말은 “surface 를 섞지 말라”는 경고로는 여전히 유효하지만, 2026년 current contract 전체를 설명하지는 못합니다. 지금 더 정확한 문장은 이렇습니다. 임의의 public URL 은 native Gemini file resource 가 아니지만, GCS object 에는 files.register 라는 official route 가 있다.
또 하나 놓치기 쉬운 경계는 resource 수명입니다. Gemini current Files API docs 는 upload 된 파일이 48시간 보존된다고 설명합니다. 어제까지 되던 요청이 오늘 비슷한 형태로 실패한다면, prompt 나 model 을 탓하기 전에 expired resource 를 먼저 확인해야 합니다.
OpenAI 호환 image_url 을 쓰는 경우
이 가지가 가장 헷갈리는 이유는 route 자체는 맞아도 같은 오류가 나올 수 있기 때문입니다. 현재 Gemini OpenAI compatibility docs는 image_url 을 쓰는 multimodal 예시를 계속 제공하고 있고, 거기에는 data:image/...;base64,... 도 들어 있습니다. 즉 data: 가 어디서나 금지된 것이 아닙니다. 호환 route 에만 속할 뿐입니다.
그래서 여기서 물어야 할 것은 “Gemini 가 data: URL 을 지원하나”가 아니라 “payload 가 문서가 기대하는 형태 그대로 도착했나”입니다. HTML escape 된 base64, wrapper 의 content item 재작성, 호환 클라이언트의 필드 변형은 route 가 맞아도 같은 unsupported-file-URI 계열 오류를 만들 수 있습니다.
수정 순서는 단순합니다. 먼저 OpenAI 호환 route 인지 확인합니다. 그다음 image_url 형태를 유지합니다. 원본 파일에서 clean base64 를 다시 만들고, 불필요한 변환 없이 재전송합니다. native Gemini file_data 논리를 이 가지에 섞지 마세요. 그러면 문제 하나가 둘이 됩니다.
이 section 을 따로 두는 이유도 같습니다. 현재 Google AI Developers Forum 에는 Unsupported file uri: data:image/png;base64,... 라는 exact symptom 사례가 있지만, 같은 시점의 official docs 는 여전히 image_url 안의 data: 를 support 합니다. publishable 한 결론은 “docs 가 틀렸다”가 아니라 “같은 오류는 wrong route 에서도, broken payload 에서도 나온다”입니다.
GCS object, public URL, Vertex path 를 쓰는 경우
public URL, 등록된 Gemini file, Vertex gs:// 는 같은 것이 아닙니다. 짧은 답변이 가장 자주 흐리는 지점이 여기입니다.
native Gemini 에 public HTTPS object URL 을 보냈다면, 보통은 “브라우저에서 열리는 object”와 “Gemini 가 읽는 file resource”를 같은 것으로 착각한 것입니다. URL 이 공개되어 있다고 해서 native Gemini file_data 에서 그대로 쓸 수 있는 것은 아닙니다. 더 안전한 수정은 Files API upload, 또는 source of truth 가 GCS 에 있다면 files.register 입니다. 등록 대상은 public web wrapper URL 이 아니라 object 그 자체입니다.
Vertex AI 에서는 사정이 다릅니다. 그쪽에서는 gs://bucket/object 가 자연스러운 shape 일 수 있습니다. 문제는 이 경험을 native Gemini 로 그대로 되가져와서, 구글 계열 image route 가 전부 같은 object contract 를 쓸 것이라 가정하는 것입니다. 실제로는 그렇지 않습니다.
그래서 이 가지에서 먼저 답해야 하는 질문은 “GCS 가 되나 안 되나”가 아니라 “지금 이 request 를 누가 소유하고 있나”입니다. native Gemini 면 upload / files.register, Vertex 면 Vertex route 유지, URI 처럼 보여서 그냥 넣은 public URL 이면 현재 surface 가 인정하는 file resource 로 바꾸는 것. 그게 가장 작은 수정입니다.
앱이 local file path 를 보낸 경우
local path 는 그럴듯해 보입니다. 실제 파일이 거기에 있기 때문입니다. 하지만 /tmp/example.png, file:///storage/... 같은 값은 기기 쪽 참조일 뿐, Gemini 가 나중에 다시 가져갈 수 있는 file resource 는 아닙니다.
가장 안전한 cross-platform rule 은 여전히 upload first 입니다. 파일을 먼저 Gemini 관리 resource 로 바꾸고, 그다음 반환된 URI 를 씁니다. 그 이전의 local path 는 “내 앱에서는 보인다”는 사실만 증명할 뿐입니다.
mobile SDK 나 wrapper 에는 content:// 같은 더 세세한 예외가 존재할 수 있습니다. 하지만 main route 를 고치기 전에는 그런 예외가 주인공이 되어서는 안 됩니다. primary repair 전부터 client-specific nuance 로 내려가면, 독자는 많이 읽고도 request 는 여전히 막힌 상태가 되기 쉽습니다.
수정 후 어떻게 검증하고, 그다음엔 무엇을 의심하나
오류가 한 번 사라졌다고 해서 문제가 완전히 닫힌 것은 아닙니다. 더 안전한 순서는 다음과 같습니다.
- 한 번에 하나의 최소 file-route 수정만 넣고, 같은 path 에서 재시도한다.
- 같은 요청이 파일을 받아들일 뿐 아니라 원래 하려던 job 도 실제로 수행하는지 본다.
- 이전에 upload / register 한 file 을 쓰고 있다면 expired resource 인지 확인한다.
- route 가 명백히 맞는데도 실패한다면 base64 integrity, wrapper rewrite, stale client code 로 넘어간다.
여기서 가장 중요한 경계는 무엇을 너무 빨리 blame 하지 말아야 하는가입니다. 이 증상은 Nano Banana Pro 가 갑자기 이미지를 이해하지 못하게 되었다는 뜻이기보다, 이미지가 supported route 로 모델에 도착하지 못했다는 뜻인 경우가 훨씬 많습니다. route 가 맞춰진 뒤에만 payload 나 platform behavior 로 넘어가야 시간을 덜 잃습니다.
그 다음 단계에서 문제의 성격이 다른 image failure class 라는 것이 드러난다면, 이어 읽기 좋은 페이지는 Gemini image common errors guide 입니다.
FAQ
native Gemini file_data 에 public HTTPS URL 을 바로 넣을 수 있나요?
보통은 안 됩니다. public object URL 과 Gemini File resource 는 다릅니다. native Gemini 에서는 upload 나, GCS object 인 경우 files.register 가 더 안전합니다.
data:image/...;base64,... 는 지원되나요?
지원됩니다. 다만 OpenAI 호환 image_url route 에서만 그렇습니다. 2026-04-09 기준 current Gemini docs 는 still support 합니다. 그 route 에서도 실패한다면 먼저 payload integrity 를 보세요.
/tmp/a.png 나 file:///... 같은 local path 를 직접 보낼 수 있나요?
재사용 가능한 Gemini file URI 처럼 직접 보내면 안 됩니다. safer 한 방식은 먼저 upload 하고 반환된 resource 를 쓰는 것입니다.
files.register 가 upload 를 대체하나요?
전부를 대체하지는 않습니다. GCS object 에 대한 official route 이고, local file 은 still upload first 입니다.
route 를 고쳐도 같은 오류가 남으면요?
그 시점에는 순수 route bug 가 아닙니다. corrupted base64, expired resource, wrapper / SDK 의 요청 변형을 확인하세요.
기억할 규칙
가장 빠른 clean fix 는 “prompt 를 바꾸는 것”도 “전부 PDF 로 몰아넣는 것”도 아닙니다. 현재 surface 를 파악하고, 그 surface 가 실제로 받는 file route 로 입력을 옮기고, 같은 path 에서 verify 한 뒤, 그래도 남을 때만 payload 나 platform behavior 를 의심하는 것입니다.