이미지 편집 시 Unable to Process Input Image가 반환되나요?

증상

참조 이미지를 사용한 이미지 편집을 위해 Nano Banana 모델(gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-nano-banana-2.1 등)을 호출할 때, API에서 다음 두 가지 오류 중 하나와 함께 HTTP 400을 반환합니다.

{
  "error": {
    "message": "Unable to process input image. Please retry or report in https://developers.generativeai.google/guide/troubleshooting",
    "code": 400
  }
}

Unable to submit request because it has an empty inlineData parameter. Add a value to the parameter and try again.

오류는 보통 일시적으로 급증했다가 멈추므로, API가 불안정한 것처럼 보일 수 있습니다.

원인

요청의 inlineData.data이(가) 비어 있어 제공업체가 이미지를 수신하지 못했습니다. 두 오류 모두 원인은 동일하며, 노드에 따라 표현 방식만 다릅니다. 하나는 inlineData 매개변수가 비어 있다고 표시합니다. 다른 하나는 “unable to process input image”라고 표시되어 이미지가 손상되었거나 해당 링크에 접근할 수 없다고 생각하게 만듭니다.

이는 이미지 URL 문제나 스토리지 버킷의 공개 여부와는 관련이 없습니다. inlineData에서는 이미지가 요청 본문 내에 base64로 전송되며, 제공업체는 링크를 전혀 가져오지 않습니다. 이 오류는 base64 문자열 자체가 비어 있음을 의미합니다. 문제는 코드에서 이미지를 base64로 변환하는 단계에 있습니다.

콘솔 로그에서 이를 확인할 수 있습니다. 실패한 요청은 입력 tokens 수가 매우 적지만(prompt만 포함), 이미지가 포함된 정상 요청은 수백 개에서 수천 개 더 많습니다.

체크리스트

다운로드 또는 인코딩 단계가 실제로 성공했습니까?

많은 프로그램이 먼저 객체 스토리지(COS / OSS / S3)에서 이미지를 다운로드한 다음 base64로 변환합니다. 다운로드에 실패하거나 시간 초과가 발생하거나, 비동기 단계가 완료되기 전에 요청이 전송되면 빈 문자열이 생성됩니다. 전송 직전에 base64 길이를 로그로 기록하십시오.

변수가 undefined 상태입니까?

JavaScript에서 JSON.stringify은(는) 값이 undefined인 필드를 경고 없이 제외합니다. imageBase64이(가) undefined인 경우, 직렬화된 요청에는 inlineData 하위에 mimeType만 포함되고 data 필드가 전혀 존재하지 않으므로 제공자 측에서 비어 있는 inlineData 오류를 보고합니다. 이는 코드상에서 확인할 수 없으므로, 실제로 전송되는 요청 본문을 로그로 기록하여 확인해야 합니다.

data에 data URL 접두사가 포함되어 있습니까?

inlineData.data에는 순수 base64만 포함되어야 합니다. 전체 data:image/png;base64,iVBORw0... 문자열이 있는 경우 쉼표(,)를 포함하여 그 앞의 모든 내용을 제거하십시오.

mimeType이 실제 이미지 형식과 일치합니까?

실제 형식에 맞춰 mimeType을(를) image/png, image/jpeg 또는 image/webp(으)로 설정하십시오. 파일 확장자는 신뢰할 수 없습니다(일부 휴대폰 .jpg 파일은 실제로는 다중 프레임 이미지입니다). 가장 안전한 방법은 변환 과정에서 모든 항목을 PNG 또는 JPEG로 다시 인코딩하는 것입니다.

전송 전 유효성 검사

요청을 생성하기 전에 몇 줄의 검사 코드를 추가하면 API 오류 대신 로컬에서 문제를 바로 발견할 수 있습니다:

JavaScript
Python

const b64 = (imageBase64 || '').replace(/^data:[^;]+;base64,/, '');
if (!b64) {
  throw new Error('Reference image base64 is empty; check the download / encoding step');
}

const payload = {
  contents: [{
    parts: [
      { text: prompt },
      { inlineData: { data: b64, mimeType: imageMimeType } }
    ]
  }],
  generationConfig: {
    responseModalities: ['IMAGE'],
    imageConfig: { imageSize: '2K' }
  }
};

import base64, re

def to_inline_data(image_bytes: bytes, mime_type: str) -> dict:
    if not image_bytes:
        raise ValueError("Reference image is empty; check the download / read step")
    b64 = base64.b64encode(image_bytes).decode()
    return {"inlineData": {"data": b64, "mimeType": mime_type}}

def strip_data_url(s: str) -> str:
    b64 = re.sub(r"^data:[^;]+;base64,", "", s or "")
    if not b64:
        raise ValueError("Reference image base64 is empty")
    return b64

이 400 오류는 요청 자체로 인해 발생하므로, 동일한 요청을 재시도해도 성공하지 않습니다. 코드를 수정한 후에는 플랫폼 측에서 별도의 설정을 변경할 필요가 없습니다.

대신 이미지 URL을 전달하고 싶으신가요?

네이티브 Gemini 엔드포인트는 이미지 링크를 직접 전달받을 수도 있습니다. fileData을 사용하고, inlineData은 사용하지 마십시오:

{
  "fileData": {
    "fileUri": "https://your-bucket.example.com/ref.png",
    "mimeType": "image/png"
  }
}

URL을 사용할 경우 Google 서버가 이미지를 다운로드해야 합니다. 스토리지 서비스가 중국 본토 CDN(예: 기본 설정의 Tencent Cloud COS)을 통해서만 제공되는 경우, Google에서 접근하지 못하는 경우가 많습니다. 일반적인 증상은 오류가 발생하는 것이 아니라 결과가 참조 이미지를 무시하는 것입니다. 가능한 경우, base64가 더 안정적인 옵션입니다. 자세한 내용은 Nano Banana 개발자 가이드를 참조하십시오.

자주 묻는 질문

이미지가 공개적으로 접근 가능한 상태인데 왜 여전히 이 오류가 발생합니까?

inlineData의 경우 제공자가 링크를 전혀 가져오지 않으므로 공개 접근 가능 여부는 영향을 주지 않습니다. 코드에서 이미지를 base64로 변환하는 단계를 확인하고, 전송하는 data 필드가 비어 있지 않은지 확인하십시오.

이러한 실패한 요청에도 과금이 됩니까?

아닙니다. 요청이 제공자의 진입 지점에서 거부되어 이미지가 생성되지 않으므로 요금이 부과되지 않습니다. 콘솔 호출 로그가 최종 기준이 됩니다.

Nano Banana 개발자 가이드

입력 이미지 요구사항, URL 입력 및 타임아웃

Gemini 이미지 오류 처리

각 오류 및 finishReason 처리 방법

이미지 MIME 타입 불일치?

이미지 URL의 처리 파라미터로 인한 포맷 불일치

이미지 압축 및 해상도

참조 이미지를 압축해도 출력 품질은 저하되지 않습니다

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 생성

음성 API (공식)

검색 및 안전

이미지 편집 시 Unable to Process Input Image가 반환되나요?

증상

원인

체크리스트

전송 전 유효성 검사

대신 이미지 URL을 전달하고 싶으신가요?

자주 묻는 질문

관련 문서

Nano Banana 개발자 가이드

Gemini 이미지 오류 처리

이미지 MIME 타입 불일치?

이미지 압축 및 해상도

​증상

​원인

​체크리스트

​전송 전 유효성 검사

​대신 이미지 URL을 전달하고 싶으신가요?

​자주 묻는 질문

​관련 문서

Nano Banana 개발자 가이드

Gemini 이미지 오류 처리

이미지 MIME 타입 불일치?

이미지 압축 및 해상도

증상

원인

체크리스트

전송 전 유효성 검사

대신 이미지 URL을 전달하고 싶으신가요?

자주 묻는 질문

관련 문서