> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Nano Banana 이미지 편집 시 400 'Unable to process input image' 또는 'empty inlineData parameter'가 반환되는 이유는 요청의 inlineData 이미지 데이터가 비어 있기 때문입니다. 이는 이미지 URL에 접근할 수 있는지 여부와는 아무런 관련이 없습니다. base64 변환 단계를 확인하고 전송 전에 유효성을 검증하십시오.

## 증상

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

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

```text theme={null}
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"라고 표시되어 이미지가 손상되었거나 해당 링크에 접근할 수 없다고 생각하게 만듭니다.

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

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

## 체크리스트

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

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

  <Step title="data에 data URL 접두사가 포함되어 있습니까?">
    `inlineData.data`에는 **순수 base64**만 포함되어야 합니다. 전체 `data:image/png;base64,iVBORw0...` 문자열이 있는 경우 쉼표(,)를 포함하여 그 앞의 모든 내용을 제거하십시오.
  </Step>

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

## 전송 전 유효성 검사

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

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    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' }
      }
    };
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>
</Tabs>

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

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

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

```json theme={null}
{
  "fileData": {
    "fileUri": "https://your-bucket.example.com/ref.png",
    "mimeType": "image/png"
  }
}
```

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

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="이미지가 공개적으로 접근 가능한 상태인데 왜 여전히 이 오류가 발생합니까?">
    `inlineData`의 경우 제공자가 링크를 전혀 가져오지 않으므로 공개 접근 가능 여부는 영향을 주지 않습니다. 코드에서 이미지를 base64로 변환하는 단계를 확인하고, 전송하는 `data` 필드가 비어 있지 않은지 확인하십시오.
  </Accordion>

  <Accordion title="이러한 실패한 요청에도 과금이 됩니까?">
    아닙니다. 요청이 제공자의 진입 지점에서 거부되어 이미지가 생성되지 않으므로 요금이 부과되지 않습니다. 콘솔 호출 로그가 최종 기준이 됩니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="Nano Banana 개발자 가이드" icon="book-open" href="/ko/api-capabilities/nano-banana-dev-guide">
    입력 이미지 요구사항, URL 입력 및 타임아웃
  </Card>

  <Card title="Gemini 이미지 오류 처리" icon="shield-alert" href="/ko/api-capabilities/gemini-image-error-handling">
    각 오류 및 finishReason 처리 방법
  </Card>

  <Card title="이미지 MIME 타입 불일치?" icon="file-warning" href="/ko/faq/image-mime-type-mismatch-with-query">
    이미지 URL의 처리 파라미터로 인한 포맷 불일치
  </Card>

  <Card title="이미지 압축 및 해상도" icon="minimize-2" href="/ko/api-capabilities/image-compression-resolution">
    참조 이미지를 압축해도 출력 품질은 저하되지 않습니다
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.