> ## 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` 等）做**帶參考圖的圖片編輯**時，介面返回 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.
```

通常是一段時間內連續報錯、換個時間又正常，看起來像是介面不穩定。

## 原因

**請求裡 `inlineData.data` 是空的，原廠沒有拿到圖片內容。** 兩句報錯是同一個原因，只是不同節點的措辭不同：一句直接說「inlineData 引數為空」，另一句說「無法處理輸入圖片」，後者容易讓人誤以為是圖片格式損壞或圖片連結打不開。

<Info>
  **和圖片 URL、圖床是否公網可讀無關。** 用 `inlineData` 傳送時，圖片是以 base64 的形式放在請求體裡的，原廠不會去訪問任何連結。報這個錯說明 base64 字串本身是空的，問題出在你的程式把圖片轉成 base64 的那一步。
</Info>

一個可以自查的旁證：在控制台日誌裡看這幾次請求，失敗的請求輸入 token 很少（只有提示詞的量），而正常帶圖的請求輸入 token 會多出幾百到幾千。

## 逐項排查

<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>

## 傳送前加一道檢查

在組裝請求之前加幾行校驗，問題會在本地直接暴露，不用等介面報錯：

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const b64 = (imageBase64 || '').replace(/^data:[^;]+;base64,/, '');
    if (!b64) {
      throw new Error('參考圖 base64 為空，請檢查下載 / 轉碼步驟');
    }

    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("參考圖內容為空，請檢查下載 / 讀取步驟")
        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("參考圖 base64 為空")
        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 傳圖時，圖片要由谷歌的伺服器去下載。如果圖床只走國內 CDN（例如騰訊雲物件儲存的預設配置），谷歌經常拉不到，表現通常是**生成結果不參考這張圖**，而不是報錯。條件允許的話，**更推薦 base64 方式**，穩定性最高。完整說明見 [Nano Banana 開發指南](/zh-Hant/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="/zh-Hant/api-capabilities/nano-banana-dev-guide">
    輸入圖片要求、URL 傳圖與超時設定
  </Card>

  <Card title="Gemini 生圖錯誤處理指南" icon="shield-alert" href="/zh-Hant/api-capabilities/gemini-image-error-handling">
    各類報錯與 finishReason 的處理方式
  </Card>

  <Card title="上傳圖片報 MIME type 不匹配？" icon="file-warning" href="/zh-Hant/faq/image-mime-type-mismatch-with-query">
    圖床連結帶處理引數導致的格式不符
  </Card>

  <Card title="圖片壓縮與解析度" icon="minimize-2" href="/zh-Hant/api-capabilities/image-compression-resolution">
    參考圖壓縮不影響輸出畫質
  </Card>
</CardGroup>


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