Nano Banana Pro에서 'Unsupported file URI type'이 뜨나? 먼저 Gemini 파일 경로부터 바로잡기

Nano Banana Pro에서 Unsupported file URI type 또는 Invalid or unsupported file uri가 뜨면 전송 직전의 이미지 값과 요청 주소부터 확인합니다. {{ $json.imageUrls }} 같은 템플릿이 그대로 남았는지, URI 자리에 배열이나 로컬 경로를 넣었는지, 사용하는 API와 필드 형식이 맞는지 살펴보세요. 프롬프트를 바꾸기 전에 이미지가 올바르게 전달됐는지 확인할 수 있습니다.

공개 HTTPS 주소를 썼다는 이유만으로 업로드부터 다시 할 필요는 없습니다. 2026년 10월 1일 업데이트된 Gemini generateContent 문서는 공개 HTTPS와 서명 URL을 fileUri로 전달하는 방식을 지원합니다. 다만 Gemini가 처리할 때 파일에 접근할 수 있어야 하며, 선택한 모델과 중간 도구의 지원 조건도 충족해야 합니다. Gemini 2.0 계열은 이 URL 입력 방식을 지원하지 않습니다. 브라우저에서 주소가 열린다는 사실만으로 모든 조건이 충족되지는 않습니다. 공식 파일 입력 방법

아래 예시는 Gemini Developer API의 generateContent에서 Nano Banana Pro로 이미지를 편집하는 경우를 기준으로 합니다. 현재 공식 Pro 모델 ID는 gemini-3-pro-image입니다. 이전 예제의 gemini-3-pro-image-preview를 사용하고 있다면 자신의 계정에서 해당 ID가 제공되는지 별도로 확인하세요. URI 오류를 없애려고 이미지 설명만 하는 모델로 바꾸면 원래의 편집 작업을 검증할 수 없습니다. 공식 이미지 생성·편집 문서

오류에 나온 값으로 먼저 고칠 곳 찾기

다음 표는 이미지 파일을 어디서 가져왔는지보다 요청에 최종적으로 무엇이 들어갔는지를 기준으로 읽습니다. 모든 잘못된 값이 똑같은 오류 문구를 반환하는 것은 아닙니다.

native 요청의 주소는 다음 형태입니다. image_url을 받는 호환 API나 외부 게이트웨이를 사용한다면 이 JSON을 그대로 섞지 않습니다.

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent

공식 API에서 contents[].parts[]의 각 Part는 텍스트, 인라인 데이터, 파일 참조 등 한 종류의 데이터를 담습니다. fileData.fileUri는 문자열 필드입니다. 텍스트와 이미지, 서로 다른 이미지는 개별 Part로 나누세요. 아래에서는 REST 스키마의 camelCase 필드를 일관되게 사용합니다. SDK가 사용하는 snake_case 이름과 중간 도구의 필드명을 임의로 섞지 않습니다. generateContent API 스키마

템플릿·배열 문제는 전송 직전 JSON에서 확인하기

워크플로 편집 화면에 올바른 주소가 보이더라도 실제 요청은 다를 수 있습니다. HTTP 요청을 보내는 단계에서 다음을 확인하세요.

1. 이미지 필드의 값이 문자열 하나인지 확인합니다. 이미지 목록이면 각 항목을 별도 Part로 변환합니다.
2. 값이 실제 주소인지 확인합니다. 필드 이름, 미평가 표현식, 문자열로 바뀐 배열이 들어가면 안 됩니다.
3. 최종 직렬화 결과에 이미지 필드가 남아 있는지 확인합니다. JavaScript 객체의 undefined 값은 JSON.stringify에서 필드 자체가 빠질 수 있습니다. String(undefined)로 만든 문자열과는 다른 문제입니다.
4. 요청 주소와 JSON을 함께 확인합니다. native parts 안에 호환 API의 image_url 항목을 넣었는지도 봅니다.

다음 JavaScript 함수는 HTTPS 참조를 만드는 단계의 자료형 검사입니다. URL의 실제 접근 가능성이나 모델의 파일 지원 여부까지 검사하지는 않습니다. 이미 데이터 URL이나 로컬 파일을 사용하려는 경우에는 다음 절의 inlineData 방식을 선택하세요.

function httpsImagePart(value, mimeType) {
  if (typeof value !== "string" || !value.trim()) {
    throw new Error("이미지 주소는 빈 문자열이 아닌 문자열이어야 합니다.");
  }
  if (value.includes("{{") || value.includes("}}")) {
    throw new Error("이미지 주소에 계산되지 않은 표현식이 남아 있습니다.");
  }
  const url = new URL(value);
  if (url.protocol !== "https:") {
    throw new Error("이 함수에는 HTTPS 이미지 주소를 넣어야 합니다.");
  }
  return { fileData: { mimeType, fileUri: value } };
}

// 실제 앞 단계의 이미지 목록에 적용합니다.
// 예시 주소는 오프라인 자료형 확인용이며 호출에 사용하지 않습니다.
const imageUrls = ["https://example.invalid/input.png"];
const imageParts = imageUrls.map((url) => httpsImagePart(url, "image/png"));
const serialized = JSON.stringify({
  contents: [{ parts: [
    { text: "제품은 유지하고 배경을 흰색으로 바꿔 주세요." },
    ...imageParts
  ] }],
  generationConfig: { responseModalities: ["TEXT", "IMAGE"] }
});

오류 메시지에 {{ $json.imageUrls }}가 그대로 나타나는 사례는 APIYI의 2026년 4월 제보 글에도 있습니다. 이는 실제 전송값을 확인할 이유가 됩니다. 모든 워크플로에서 같은 설정이 원인이거나 특정 설정 변경이 반드시 해결한다는 뜻은 아닙니다. 로그를 공유할 때는 API 키, 서명 URL의 쿼리 문자열, 사적인 이미지 내용을 가리고 값의 종류와 필드 위치를 남기세요.

native 이미지 편집 요청 만들기: URL과 원본 바이트

현재 generateContent에서 URL을 쓰려면 이미지 Part를 다음처럼 구성합니다. fileUri는 소유하거나 사용 권한이 있는 실제 이미지 파일의 공개·서명 HTTPS 주소로 바꿔야 합니다. 아래 주소는 자리표시자입니다.

{
  "contents": [{
    "parts": [
      { "text": "제품은 유지하고 배경을 흰색으로 바꿔 주세요." },
      {
        "fileData": {
          "mimeType": "image/png",
          "fileUri": "https://YOUR_HOST.example/input.png"
        }
      }
    ]
  }],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

주소가 이미지 표시용 웹페이지나 로그인 화면을 반환하지 않는지, 실제 파일 형식이 image/png와 일치하는지 확인합니다. 서명 URL은 요청 처리 중에도 유효해야 합니다. 내 브라우저의 로그인 쿠키가 있어야 열리는 주소는 서버의 접근 가능성을 입증하지 못합니다. 비공개 파일을 공개로 바꾸기보다 기존 보안 정책에 맞는 서명 URL이나 원본 바이트 전송을 선택하세요. URL 안전성 검사에서 URL_RETRIEVAL_STATUS_UNSAFE가 반환됐다면 이를 우회하는 주소를 찾는 대신 거절 사유를 확인합니다. URL 입력 조건

서버가 URL에서 파일을 가져오는 과정과 이미지 입력 형식을 따로 확인하려면 작은 로컬 이미지 한 장을 inlineData로 보내는 방법이 유용합니다. 다음 코드를 build_request.py로 저장하고, 실제 PNG 파일을 input.png로 준비하세요. 파일 이름만 PNG로 바꾸면 안 됩니다. 이 스크립트는 로컬에서 요청 JSON을 만들며 네트워크 호출은 하지 않습니다.

import base64
import json
from pathlib import Path

raw = Path("input.png").read_bytes()
if not raw.startswith(b"\x89PNG\r\n\x1a\n"):
    raise ValueError("input.png에 실제 PNG 파일을 준비하세요.")

payload = {
    "contents": [{"parts": [
        {"text": "제품은 유지하고 배경을 흰색으로 바꿔 주세요."},
        {"inlineData": {
            "mimeType": "image/png",
            "data": base64.b64encode(raw).decode("ascii")
        }}
    ]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}
Path("request.json").write_text(
    json.dumps(payload, ensure_ascii=False), encoding="utf-8"
)

python3 build_request.py

inlineData.data에는 data:image/png;base64, 접두어를 붙이지 않습니다. 원본 파일 바이트를 Base64로 변환해야 하며, URL 글자나 이미 Base64인 문자열을 다시 인코딩하면 원본 이미지가 되지 않습니다. JPEG나 WebP를 사용할 때는 실제 형식에 맞게 MIME와 파일 확인 부분을 바꿉니다. 인라인 이미지와 Part 형식

자신의 Gemini API 키가 GEMINI_API_KEY에 설정되어 있고 Pro 모델 접근 권한이 있다면 다음 요청으로 request.json을 보낼 수 있습니다. URL 방식도 같은 JSON 파일에 위의 URL 요청을 저장해 같은 주소로 보냅니다. 실제 호출에는 계정의 사용량·과금 조건이 적용됩니다.

curl --fail-with-body \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

작은 이미지 한 장으로 URL과 인라인 전송을 각각 비교하되 모델, 편집 지시, 출력 설정은 유지하세요. 인라인으로는 편집 이미지가 나오고 URL로만 실패한다면 URL의 접근·만료·중간 도구 변환을 우선 확인할 수 있습니다. 둘 다 실패하면 각각의 오류 응답을 기준으로 모델 접근, 입력 형식, 요청 크기 등을 다시 구분합니다. 한 번의 결과로 원인을 확정하는 절차는 아닙니다.

공식 파일 입력 문서의 일반 한도는 인라인·외부 URL 입력의 요청 페이로드당 100MB를 안내합니다. 이는 모든 Pro 이미지나 게이트웨이가 100MB를 받는다는 보장이 아닙니다. 해당 방법뿐 아니라 선택한 모델, 파일 형식, 토크나이저와 사용 도구의 제한을 함께 확인하세요. 입력 방법별 한도

Files API를 쓴다면 반환된 URI와 파일 상태 확인하기

같은 이미지를 여러 요청에서 재사용하거나 로컬 파일을 업로드하는 흐름이라면 Files API를 사용할 수 있습니다. 생성 요청에는 업로드 응답의 uri를 그대로 넣습니다. name의 files/… 값은 파일 조회용 식별자이며 URI를 만들어 붙이는 재료가 아닙니다. 로컬 경로를 그 자리에 재사용해서도 안 됩니다. File 리소스와 조회 API

다음은 공식 Python SDK가 이미 설치된 환경에서 업로드 후 요청 파일을 만드는 예입니다. 앞 절의 JSON과 동일한 편집 설정을 사용합니다. 이 코드는 실제 실행하면 업로드·상태 조회를 하므로 로컬 JSON 생성 예제와 구분하세요.

import json
import time
from pathlib import Path
from google import genai

client = genai.Client()
uploaded = client.files.upload(
    file="input.png", config={"mime_type": "image/png"}
)

for _ in range(30):
    current = client.files.get(name=uploaded.name)
    state = current.state.name if current.state else "STATE_UNSPECIFIED"
    if state == "ACTIVE":
        break
    if state == "FAILED":
        raise RuntimeError("파일 처리에 실패했습니다. File 응답의 error를 확인하세요.")
    time.sleep(2)
else:
    raise TimeoutError("파일이 준비되지 않았습니다. 현재 상태를 확인하세요.")

if not current.uri or not current.mime_type:
    raise ValueError("File 응답에 uri 또는 mime_type이 없습니다.")

payload = {
    "contents": [{"parts": [
        {"text": "제품은 유지하고 배경을 흰색으로 바꿔 주세요."},
        {"fileData": {
            "mimeType": current.mime_type,
            "fileUri": current.uri
        }}
    ]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}
Path("request.json").write_text(
    json.dumps(payload, ensure_ascii=False), encoding="utf-8"
)

PROCESSING은 아직 추론에 사용할 준비가 되지 않은 상태이고, ACTIVE는 준비된 상태, FAILED는 처리 실패입니다. 무한 재시도 대신 일정 시간 안에 준비되지 않으면 상태와 오류를 확인합니다. 요청 JSON이 만들어지면 앞 절의 같은 Pro generateContent 요청으로 보냅니다.

일반적인 Files API 업로드 파일은 48시간 보관됩니다. 지난 실행의 URI를 저장해 계속 쓰고 있었다면 파일을 조회해 상태와, 응답에 있는 경우 expirationTime을 확인하세요. 만료됐다면 원본 파일을 다시 업로드하고 새 응답의 URI로 바꿉니다. 이 48시간을 GCS 등록 파일이나 외부 서비스의 결과 URL에 그대로 적용하지 않습니다. 파일 수명과 입력 방법

GCS와 Vertex는 요청 주소·인증부터 구분하기

원본이 GCS에 있다면 Gemini Developer API의 files.register로 등록한 뒤 반환된 URI를 사용할 수 있습니다. 등록은 파일을 복사하는 업로드와 다릅니다. 다음은 등록 요청의 주소와 JSON 형식이며, 버킷과 객체 이름은 실제 사용 권한이 있는 값으로 바꿉니다.

POST https://generativelanguage.googleapis.com/v1beta/files:register

{
  "uris": ["gs://YOUR_BUCKET/input.png"]
}

실제 적용 순서는 다음과 같습니다.

1. 공식 등록 문서에 따라 호출자의 OAuth 인증·범위·권한과 필요한 API 및 서비스 ID를 확인합니다. 등록에 API 키 하나만 있으면 된다고 가정하지 않습니다.
2. Gemini 서비스 에이전트가 대상 버킷의 객체를 읽을 수 있는지 확인합니다. 공식 안내는 해당 버킷 범위의 Storage Object Viewer 권한을 사용합니다. 기존 접근 정책 안에서 관리자와 확인하세요.
3. 등록 응답의 files[]에서 대상 파일의 uri와 MIME를 가져와 앞의 fileData에 넣습니다. 이후 생성 요청에는 생성 API에 맞는 인증을 사용합니다.
4. 등록 접근 기간이 지났거나 객체 접근 권한이 바뀌었다면 해당 조건을 먼저 확인하고 필요할 때 다시 등록합니다.

한 번의 GCS 등록으로 최대 30일 동안 접근할 수 있으며, 파일은 요청마다 가져옵니다. 등록 대상 중 하나가 실패하면 전체 등록이 실패하므로 먼저 한 객체로 확인하는 편이 진단하기 쉽습니다. GCS 등록과 인증 조건, files.register 응답

이미 Vertex AI를 사용하는 요청이라면 프로젝트·위치·게시자 모델 경로와 그 인증 규칙을 따릅니다. gs://라는 문자열이 같아도 Gemini Developer API의 등록 요청과 Vertex 생성 요청은 같은 작업이 아닙니다. API 키와 OAuth 구분이 제기된 2025년 Gemini 2.0 포럼 사례를 현재 Pro의 HTTPS 지원 여부에 대한 근거로 확대하지 마세요. 이 오류를 고치려고 사용하던 native API를 Vertex로 옮길 필요는 없습니다.

호환 API·게이트웨이에서는 어떤 JSON이 나가는지 비교하기

Gemini의 OpenAI 호환 API는 /v1beta/openai/에서 별도의 요청 형식을 사용합니다. 공식 이미지 이해 예제의 사용자 메시지에는 다음과 같은 content 항목이 들어갑니다.

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,BASE64_OF_IMAGE_BYTES"
  }
}

이 data URL 접두어는 호환 API의 image_url.url에 해당합니다. native fileData.fileUri나 inlineData.data에 그대로 옮기지 않습니다. 반대로 이미 호환 API를 쓰고 있다면 native parts를 섞는 대신 해당 요청의 메시지·content 형식과 실제 모델·작업 지원을 확인합니다. 공식 OpenAI 호환 문서

호환 문서의 이미지 이해 예제가 답변 텍스트를 반환한다고 해서 Pro 편집 이미지까지 생성할 수 있다는 뜻은 아닙니다. 이미지 생성 API의 작업과 출력 계약도 따로 확인해야 합니다. 이 글의 native Pro 편집 예제를 호환 API의 이미지 설명 요청으로 바꿔 URI 문제가 해결됐다고 판단하지 마세요.

직접 SDK에서는 성공하고 게이트웨이에서만 실패한다면 같은 URL을 보냈다는 사실보다 실제로 전송된 이미지 Part가 같은지가 중요합니다. Vercel AI SDK issue 10692의 2025년 제보는 게이트웨이가 서명 URL을 그대로 넘기는 반면 직접 제공자 SDK는 이미지를 내려받아 바이트로 보내는 차이를 설명합니다. 제보 당시 버전은 ai 5.0.104, Google 제공자 2.0.44, Gateway 2.0.17입니다. 닫힌 과거 이슈이며 현재 버전의 동일한 결함이나 수정 상태를 입증하지는 않습니다.

이 차이가 있다면 직접 SDK의 성공은 서버가 그 URL을 가져왔다는 증거가 아닐 수 있습니다. 사용하는 제공자·게이트웨이 버전, 최종 요청 주소, URL이 남았는지 인라인 바이트로 바뀌었는지를 비교합니다. 원본 로그를 공유하기보다 비밀값을 제거한 필드 구조와 자료형을 남기세요. 특정 버전으로 내리거나 올리면 반드시 해결된다고 단정할 근거는 없습니다.

같은 inlineData라는 이름을 쓰는 외부 API도 자체 제한을 둘 수 있습니다. 예를 들어 Comfy의 Pro API 문서는 api.comfy.org 호스트와 별도의 키를 사용하며 인라인 입력 20MB, 생성 이미지 서명 URL 24시간을 안내합니다. 이는 Google Files 업로드의 48시간이나 GCS 등록의 최대 30일과 다른 조건입니다. 필드가 닮았다는 이유로 호스트·인증·크기·만료 규칙까지 같다고 보지 않습니다.

HTTP 200보다 편집 결과 이미지를 확인하기

URI 오류가 사라졌다면 다음으로 응답의 이미지 Part와 실제 편집 내용을 확인합니다. 텍스트 설명만 받았거나 입력 이미지를 그대로 돌려받았다면 원하는 이미지 편집을 완료한 것은 아닙니다. 모델 ID와 responseModalities, 응답의 candidates[].content.parts[]를 함께 봅니다. 공식 편집 응답 예제

앞의 REST 요청으로 받은 response.json에서 이미지를 저장하는 예입니다. 오류 응답이나 이미지가 없는 응답은 성공으로 처리하지 않습니다. 저장 후에는 파일을 직접 열어 제품이 유지되고 배경이 바뀌었는지 확인하세요.

import base64
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8"))
if response.get("error"):
    raise RuntimeError("API 오류 응답입니다. error의 code와 message를 확인하세요.")

extensions = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}
saved = []
for candidate in response.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        image = part.get("inlineData")
        if not image or not image.get("data"):
            continue
        mime = image.get("mimeType", "")
        if mime not in extensions:
            raise ValueError(f"출력 이미지 형식을 확인하세요: {mime}")
        output = Path(f"edited-{len(saved) + 1}.{extensions[mime]}")
        output.write_bytes(base64.b64decode(image["data"], validate=True))
        saved.append(output)

if not saved:
    raise RuntimeError("이미지 Part가 없습니다. 후보의 종료 사유와 응답 내용을 확인하세요.")
for output in saved:
    print(output)

원하는 편집 이미지가 나왔다면 입력 방식이 받아들여졌고 이번 작업이 완료됐음을 확인할 수 있습니다. 한 번의 성공으로 모든 URL·파일·중간 도구의 호환성을 보장할 수는 없습니다. 반대로 이제 403, 모델 관련 404, 할당량 429 또는 대화의 thought signature 오류가 나온다면 그 구체적인 응답을 새 증상으로 다루세요. 계속 URI 문자열만 바꾸면 해당 문제를 해결할 수 없습니다.

이 글의 요청 예시는 공식 형식에 맞춰 구성했으며 JSON 직렬화·Base64·응답 처리 분기는 로컬에서 확인했습니다. 실제 Gemini 추론이나 업로드, 게이트웨이 호출을 재현한 성공 로그는 아닙니다.

자주 묻는 질문

공개 HTTPS URL은 이제 바로 넣을 수 있나요?

조건에 맞는 native generateContent 요청에서는 가능합니다. 현재 공식 파일 입력 문서는 공개 HTTPS와 서명 URL을 지원하며, Gemini 2.0 계열은 제외합니다. 처리 시점의 접근 가능성, 안전성, 파일 형식, 선택 모델과 중간 도구의 조건은 여전히 확인해야 합니다. fileUri에는 실제 파일 주소 한 개를 문자열로 넣습니다. 공식 URL 입력 안내

data URL에서 접두어만 지우면 해결되나요?

native inlineData.data로 보낼 때는 원본 이미지 바이트의 Base64만 필요합니다. 이미 올바르게 만들어진 data URL이라면 Base64 부분을 사용할 수 있지만 MIME와 바이트가 맞는지도 확인해야 합니다. 단순히 접두어를 지우고 fileUri에 넣으면 이미지 입력 형식이 맞지 않습니다. 호환 API의 image_url.url은 data URL 접두어를 유지하는 별도의 형식입니다. native Part 스키마, 호환 이미지 입력

어제 되던 업로드 URI가 오늘 실패하면 무엇부터 보나요?

파일의 현재 상태와 만료 여부부터 확인합니다. 일반 Files API 업로드는 48시간 보관되므로 기존 URI가 만료됐다면 다시 업로드한 URI로 교체합니다. 등록한 GCS 파일이나 외부 서비스의 서명 URL이라면 각각의 접근 기간과 권한을 확인해야 합니다. 모든 파일 참조에 48시간 규칙이 적용되는 것은 아닙니다. 입력 방법별 수명

이미지 여러 장은 fileUri 배열로 보내나요?

아닙니다. native API의 fileData.fileUri는 문자열입니다. 이미지마다 fileData 또는 inlineData를 담은 Part를 만들고 parts[]에 추가합니다. 모델별 이미지 수와 요청 크기 제한도 따로 확인하세요. Content·Part·FileData 정의

파일이 ACTIVE라면 Pro 편집도 성공한 건가요?

아닙니다. ACTIVE는 파일 처리 상태가 준비됐다는 뜻입니다. 선택한 Pro 모델이 해당 입력으로 편집 이미지를 생성했는지는 생성 응답의 이미지 Part를 저장하고 실제 결과를 열어 확인해야 합니다. 파일 준비, 요청 성공, 원하는 편집 완료는 각각 확인할 대상입니다. File 상태, 이미지 편집 응답