|

gemini-3-pro-image-preview Base64 decoding failed 錯誤：6 大原因與完整修復指南

ByAPIYI - Stable and affordable AI API

作者注：調用 gemini-3-pro-image-preview 報 Base64 decoding failed 400 錯誤？本文從原始錯誤信息出發，分析 6 大常見原因，提供 Python/JavaScript/curl 三種語言的正確示例和 5 步排查方案。

調用 gemini-3-pro-image-preview 接口時遇到這條 400 錯誤？

{
  "status_code": 400，
  "error": {
    "message": "Invalid value at 'contents[0].parts[0].inline_data.data' （TYPE_BYTES）， Base64 decoding failed for \"/9j/4AAQSkZJ...\" （request id: 2026050117522815159336234238114）"，
    "type": "shell_api_error"，
    "code": 400
  }
}

這不是 API 服務的問題，而是請求體中 inline_data.data 字段的 Base64 數據無法被 Gemini 後端正確解碼。錯誤信息中的 /9j/4AAQSkZJ 是 JPEG 文件的標準 Base64 頭部（對應二進制 FF D8 FF E0），說明你的數據起始部分是合法的，但完整字符串中存在某些導致解碼失敗的問題。

核心價值: 本文將完整剖析這條錯誤的 6 大常見原因，提供針對 Python、JavaScript、curl 三種調用方式的正確示例代碼，並給出一個 5 步快速定位方案。如果你正在使用 API易 apiyi.com 調用 gemini-3-pro-image-preview，本文的所有解決方案同樣適用。

gemini-3-pro-image-preview-base64-decoding-failed-fix-zh-hant 图示

一、Base64 decoding failed 錯誤深度解讀

在動手排查之前，先理解這條錯誤信息每個字段的含義，能幫你少走 80% 的彎路。

1.1 錯誤信息逐字段解讀

字段 含義 排查方向
status_code: 400 HTTP 400 客戶端錯誤 請求體格式問題，不是服務端故障
contents[0].parts[0] 錯誤定位在第 1 條 content 的第 1 個 part 檢查首個圖像 part
inline_data.data 內聯數據的 data 字段 該字段必須是純 Base64 字符串
（TYPE_BYTES） 字段類型爲字節數組 Gemini 後端期望解碼後是 bytes
Base64 decoding failed for "/9j/..." 解碼失敗，已讀取的開頭是 /9j/ 起始字節合法，問題在中間或末尾
request id: 2026050... 請求唯一 ID 聯繫技術支持時提供這個 ID

1.2 爲什麼 /9j/4AAQSkZJ 起始卻仍然失敗

/9j/4AAQSkZJ 是 JPEG 文件 Base64 編碼的標準開頭（對應二進制 FF D8 FF E0 00 10 4A 46 49 46，即 JPEG SOI + APP0 + "JFIF" 標識）。這說明：

  • ✅ 你的數據確實是 JPEG 圖像
  • ✅ 起始字節完全合法
  • ❌ 但完整字符串在某處出現了非法字符或結構問題

這個特徵排除了"數據完全錯誤"的可能，問題更可能出在數據的中間部分、末尾padding、或字符串的傳輸/轉義環節。

1.3 哪些場景會觸發這個錯誤

gemini-3-pro-image-preview 是 Google 最新的圖像生成與編輯模型，在以下場景需要傳入 inline_data：

  • 圖生圖（Image-to-Image）：基於參考圖生成新圖
  • 圖像編輯：在原圖上做局部修改
  • 多圖融合：傳入多張參考圖組合生成
  • 風格遷移：以參考圖作爲風格模板

任何需要傳入圖像數據作爲輸入的場景，都可能遇到 Base64 decoding failed 錯誤。

💡 快速診斷建議：如果你在使用 API易 apiyi.com 中轉 gemini-3-pro-image-preview，可以在控制檯查看完整的請求日誌和 request_id，對比請求體中實際發送的 inline_data.data 長度和內容，比直連官方接口排查效率高很多。

二、Base64 decoding failed 錯誤的 6 大常見原因

按出現頻率從高到低排列，建議按順序排查。

2.1 原因一：包含 data URI 前綴（最常見，約 40% 案例）

這是迄今爲止最常見的錯誤。開發者往往直接把 HTML/前端的 base64 字符串複製過來：

❌ 錯誤的寫法：

{
  "inline_data": {
    "mime_type": "image/jpeg"，
    "data": "data:image/jpeg；base64，/9j/4AAQSkZJRgABAQAA..."
  }
}

✅ 正確的寫法：

{
  "inline_data": {
    "mime_type": "image/jpeg"，
    "data": "/9j/4AAQSkZJRgABAQAA..."
  }
}

data:image/jpeg；base64， 這個前綴只在瀏覽器 <img> 標籤或 CSS background 中使用，Gemini API 的 inline_data.data 字段只接受純 Base64 字符串。

2.2 原因二：字符串中包含換行符或空白字符（約 25% 案例）

很多語言的 Base64 編碼函數會按 76 字符一行自動換行（PEM 格式），或者你從某個文件讀取時引入了 \n \r 字符。

❌ 問題示例（Python）：

import base64

# 錯誤：使用 encodebytes（） 會插入換行符
with open（"photo.jpg"， "rb"） as f:
    data = base64.encodebytes（f.read（））.decode（）  # 含 \n

✅ 正確寫法：

import base64

# 正確：使用 b64encode（） 不會插入換行
with open（"photo.jpg"， "rb"） as f:
    data = base64.b64encode（f.read（））.decode（"utf-8"）

2.3 原因三：URL 編碼導致字符替換（約 15% 案例）

Base64 字符集包含 + 和 /，在 URL 傳輸中可能被編碼成 %2B 和 %2F。某些 HTTP 客戶端會自動做 URL 編碼，導致 Gemini 後端解碼失敗。

❌ 錯誤現象：

原始: /9j/4AAQSkZJRg+abc=
傳輸後: %2F9j%2F4AAQSkZJRg%2Babc%3D

✅ 解決方案：

  • 確保 Content-Type 是 application/json，而不是 application/x-www-form-urlencoded
  • 在 JSON body 中傳輸 Base64，而不是 URL query 參數
  • 使用 HTTP 客戶端的 json= 參數（如 Python requests），而不是手動拼接

2.4 原因四：Base64 字符串被截斷（約 10% 案例）

如果你的圖像很大（數 MB），在傳輸過程中可能因爲以下原因被截斷：

  • 網絡中斷重傳
  • HTTP 客戶端的字符串長度限制
  • JSON 序列化時被字段長度限制截斷
  • 中間代理的 body size 限制

排查方法：計算原始 Base64 字符串長度，對比實際發送的請求體長度。Base64 編碼後長度約爲原文件的 4/3 倍，一張 2MB 的 JPEG 編碼後約 2.67MB。

2.5 原因五：URL-safe Base64 編碼（約 5% 案例）

Python 的 base64.urlsafe_b64encode（）、Node.js 的 Buffer.from（buf）.toString（'base64url'） 會輸出 URL-safe Base64，使用 - 和 _ 替代 + 和 /。

❌ 錯誤：

data = base64.urlsafe_b64encode（image_bytes）.decode（）  # 含 - 和 _

✅ 正確：

data = base64.b64encode（image_bytes）.decode（"utf-8"）  # 含 + 和 /

Gemini API 只接受標準 Base64（RFC 4648 §4），不接受 URL-safe Base64（RFC 4648 §5）。

2.6 原因六：缺失或多餘的 padding（約 5% 案例）

Base64 字符串長度必須是 4 的倍數，末尾用 = 填充。某些庫的"嚴格模式"會去掉末尾 =，導致 Gemini 後端解碼失敗。

❌ 錯誤：

/9j/4AAQSkZJRgABAQAAAQABAAD  ← 長度 27，不是 4 的倍數

✅ 正確：

/9j/4AAQSkZJRgABAQAAAQABAAD=  ← 末尾補 =，長度 28

如果使用 base64.b64encode（） 標準函數，padding 會自動正確處理，無需手動添加。

三、5 步快速排查 Base64 decoding failed 錯誤

gemini-3-pro-image-preview-base64-decoding-failed-fix-zh-hant 图示

按以下順序逐項檢查，絕大多數 Base64 decoding failed 錯誤都能在前 3 步內定位。

3.1 第一步：檢查 data URI 前綴

檢查動作：

# Python 示例
if data.startswith（"data:"）:
    print（"⚠️ 含有 data URI 前綴，需要去除"）
    data = data.split（"，"， 1）[1]  # 去除 data:image/...；base64，

通過條件：data 字段以 /9j/（JPEG）、iVBORw0KGgo（PNG）、R0lGOD（GIF）、UklGR（WebP）等圖像格式頭開頭，不含 data: 前綴。

3.2 第二步：清理換行和空白字符

檢查動作：

# 移除所有空白字符
import re
data = re.sub（r"\s+"， ""， data）

通過條件：字符串不含 \n \r \t 或空格。

3.3 第三步：驗證 Base64 合法性

在發送請求前先本地解碼一次，如果本地都解碼失敗，肯定有問題：

import base64
try:
    decoded = base64.b64decode（data， validate=True）
    print（f"✅ 解碼成功，原始字節數：{len（decoded）}"）
except Exception as e:
    print（f"❌ 解碼失敗：{e}"）

如果本地解碼成功但接口仍報錯，進入第四步。

3.4 第四步：驗證 mime_type 正確性

mime_type 必須與實際圖像格式一致。常見的合法值：

實際格式 正確的 mime_type Base64 頭部特徵
JPEG image/jpeg /9j/4AAQSkZJ
PNG image/png iVBORw0KGgo
WebP image/webp UklGR
GIF image/gif R0lGOD
HEIC image/heic AAAAFGZ0eXBoZWlj

如果你聲明 mime_type: image/png 但數據是 JPEG（/9j/ 開頭），Gemini 也會報錯。

3.5 第五步：檢查圖像尺寸限制

Gemini API 對單次請求的總大小有限制：

  • inline_data 總大小 ≤ 20MB（編碼前）
  • 單張圖像 建議 ≤ 7MB（編碼前）
  • 超大圖像 應使用 File API 上傳後引用

如果圖像過大，建議先壓縮或縮放再傳輸。

🎯 診斷技巧：如果你通過 API易 apiyi.com 調用 gemini-3-pro-image-preview，可以在控制檯用 request_id 反查完整請求體和響應日誌，比直連官方更容易定位問題。中轉日誌會顯示請求體的實際大小和被截斷的位置。

四、gemini-3-pro-image-preview 各語言正確調用示例

下面是經過驗證的最簡正確示例，複製即可使用。

4.1 Python 完整示例（推薦使用 requests 庫）

import base64
import requests

# 1. 讀取並編碼圖像
def encode_image（image_path）:
    with open（image_path， "rb"） as f:
        return base64.b64encode（f.read（））.decode（"utf-8"）

# 2. 構造請求
api_key = "sk-your-apiyi-key"  # 替換爲實際 API Key
base_url = "https://vip.apiyi.com/gemini"  # API易中轉地址
model = "gemini-3-pro-image-preview"

image_b64 = encode_image（"input.jpg"）

payload = {
    "contents": [{
        "parts": [
            {
                "inline_data": {
                    "mime_type": "image/jpeg"，  # 必須與實際格式一致
                    "data": image_b64  # 純 Base64，無前綴
                }
            }，
            {
                "text": "把這張圖改成梵高星空風格"
            }
        ]
    }]
}

# 3. 發起請求
response = requests.post（
    f"{base_url}/v1beta/models/{model}:generateContent"，
    headers={
        "x-goog-api-key": api_key，
        "Content-Type": "application/json"  # 關鍵：JSON 格式
    }，
    json=payload  # 關鍵：使用 json= 而不是 data=
）

print（response.json（））

4.2 JavaScript / Node.js 完整示例

const fs = require（'fs'）；
const fetch = require（'node-fetch'）；

async function callGemini（） {
  // 1. 讀取並編碼圖像（標準 Base64，非 base64url）
  const imageBuffer = fs.readFileSync（'input.jpg'）；
  const imageB64 = imageBuffer.toString（'base64'）； // ✅ 不要用 'base64url'

  // 2. 構造請求
  const apiKey = 'sk-your-apiyi-key'；
  const baseUrl = 'https://vip.apiyi.com/gemini'； // API易中轉
  const model = 'gemini-3-pro-image-preview'；

  const payload = {
    contents: [{
      parts: [
        {
          inline_data: {
            mime_type: 'image/jpeg'，
            data: imageB64  // 純 Base64
          }
        }，
        { text: '把這張圖改成梵高星空風格' }
      ]
    }]
  }；

  // 3. 發起請求
  const response = await fetch（
    `${baseUrl}/v1beta/models/${model}:generateContent`，
    {
      method: 'POST'，
      headers: {
        'x-goog-api-key': apiKey，
        'Content-Type': 'application/json'
      }，
      body: JSON.stringify（payload）
    }
  ）；

  console.log（await response.json（））；
}

callGemini（）；

4.3 curl 命令行示例

# 1. 編碼圖像並保存到文件（避免命令行長度限制）
base64 -i input.jpg -o input.b64
# 或 macOS 下：base64 -w 0 input.jpg > input.b64

# 2. 構造 JSON payload
cat > payload.json <<EOF
{
  "contents": [{
    "parts": [
      {
        "inline_data": {
          "mime_type": "image/jpeg"，
          "data": "$（cat input.b64）"
        }
      }，
      { "text": "把這張圖改成梵高星空風格" }
    ]
  }]
}
EOF

# 3. 發起請求
curl -X POST \
  "https://vip.apiyi.com/gemini/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: sk-your-apiyi-key" \
  -H "Content-Type: application/json" \
  -d @payload.json

⚠️ curl 注意事項：直接 curl -d "$（base64 input.jpg）" 在 macOS 默認會引入換行符。務必先用 base64 -w 0（Linux）或 base64 -i ... | tr -d '\n'（macOS）去除換行。

五、錯誤請求 vs 正確請求：完整對比

gemini-3-pro-image-preview-base64-decoding-failed-fix-zh-hant 图示

檢查項 錯誤示例 正確示例
data 字段開頭 data:image/jpeg；base64，/9j/... /9j/4AAQSkZJ...
換行處理 包含 \n 每 76 字符一換行 單行連續字符串
字符集 含 - _（URL-safe） 含 + /（標準）
末尾 padding 無 = 或多餘 = 自動正確 padding
mime_type 與實際格式不符 與實際格式嚴格一致
HTTP 頭 application/x-www-form-urlencoded application/json
傳輸方式 URL query 參數 JSON body 字段
圖像大小 > 20MB 單圖 單圖 ≤ 7MB

六、API易調用 gemini-3-pro-image-preview 優勢

如果排查仍無法定位問題，使用 API易 apiyi.com 中轉 gemini-3-pro-image-preview 有幾個明顯的便利：

優勢 說明
完整請求日誌 控制檯可查看 request_id 對應的完整請求/響應
錯誤快速反查 通過 request_id 一鍵定位失敗原因
原生格式兼容 無需修改代碼，僅替換 base_url 即可
不限併發 批量圖像編輯場景不會被限流
充值優惠 充值 100 美金送 10%（≈ 官網 85 折）
國內人民幣充值 微信/支付寶直接支付

接入 API易 調用 gemini-3-pro-image-preview 只需修改兩個變量：

# 官方接口
base_url = "https://generativelanguage.googleapis.com"

# 改爲 API易中轉（其餘代碼完全不變）
base_url = "https://vip.apiyi.com/gemini"

七、Base64 decoding failed 常見問題 FAQ

Q1: 爲什麼本地 base64.b64decode（） 能解碼成功，調用 API 還是報錯？

最可能的原因是傳輸環節出問題。常見情況：

  • HTTP 客戶端把 + 編碼成 %2B（應使用 application/json 而不是 form-urlencoded）
  • JSON 序列化時字符串被截斷（檢查 body 大小限制）
  • 中間代理或網關有 body size 限制（如 nginx client_max_body_size）

如果你懷疑是網絡環節的問題，可以使用 API易 apiyi.com 中轉，控制檯日誌會顯示請求體到達中轉服務器時的實際內容，便於定位。

Q2: gemini-3-pro-image-preview 支持哪些圖像格式？

支持的 mime_type 包括：

  • image/jpeg（推薦，文件最小）
  • image/png（含透明通道場景）
  • image/webp（兼顧質量和體積）
  • image/gif（僅取第一幀）
  • image/heic / image/heif（iPhone 拍攝格式）

不支持 BMP、TIFF、SVG 等格式，需要先轉換。

Q3: 一個 request 能傳幾張圖？

gemini-3-pro-image-preview 單次請求最多支持：

  • inline_data parts：3-5 張（取決於圖像總大小）
  • 總數據量：≤ 20MB（編碼前所有 inline_data 之和）
  • 建議組合：如需 5 張以上圖像參考，使用 File API 上傳後通過 file_data 引用

Q4: 報 Base64 decoding failed 但其他模型（如 gemini-2.5-flash）正常？

這種情況通常是 gemini-3-pro-image-preview 對圖像格式的嚴格性更高。新模型的輸入校驗更嚴：

  • 舊模型可能容忍部分前綴或換行
  • 新模型嚴格按 RFC 4648 §4 校驗
  • 建議按本文 4.1 的最簡正確示例重寫，逐項驗證

Q5: 用 API易 apiyi.com 調用時，使用什麼 base_url？

API易調用 gemini-3-pro-image-preview 的標準 base_url 是：

https://vip.apiyi.com/gemini

完整的端點路徑是：

https://vip.apiyi.com/gemini/v1beta/models/gemini-3-pro-image-preview:generateContent

API Key 通過請求頭 x-goog-api-key 傳遞，與 Google 官方完全一致。

Q6: request_id 的作用是什麼？

request_id（如 2026050117522815159336234238114）是這次請求的唯一標識，作用：

  • 聯繫技術支持時提供，可快速定位問題
  • 復現問題時引用，技術團隊可以查到完整請求日誌
  • 統計錯誤模式，多個 request_id 出現相同錯誤說明系統性問題

如果你使用 API易 apiyi.com 中轉，可以在控制檯直接搜索 request_id 查看詳情，無需額外聯繫。

Q7: 圖像太大該如何壓縮？

推薦使用 Pillow 在客戶端預先壓縮：

from PIL import Image
import io
import base64

def compress_image（path， max_size_kb=2048）:
    img = Image.open（path）
    # 縮放最長邊到 1568（Gemini 推薦）
    img.thumbnail（（1568， 1568））
    buffer = io.BytesIO（）
    img.save（buffer， format="JPEG"， quality=85， optimize=True）
    return base64.b64encode（buffer.getvalue（））.decode（"utf-8"）

壓縮後通常能保持視覺質量同時大幅降低體積，避免觸發 20MB 限制。

Q8: 錯誤信息顯示 （TYPE_BYTES） 是什麼意思？

TYPE_BYTES 是 Google Protocol Buffers 的字段類型標識，表示該字段在 Gemini 後端期望接收的是 解碼後的字節數組（bytes）。當 Base64 解碼失敗時，無法得到 bytes，所以報這個錯誤。這是底層 protobuf 校驗的提示，非配置問題。

八、Key Takeaways 核心要點

  • ✅ 錯誤本質：inline_data.data 字段的 Base64 字符串無法被 Gemini 後端解碼
  • ✅ 6 大常見原因（按頻率）：data URI 前綴 / 換行符 / URL 編碼 / 截斷 / URL-safe 字符 / padding 錯誤
  • ✅ 5 步排查流程：去前綴 → 清空白 → 本地驗證 → 檢查 mime_type → 檢查大小
  • ✅ Python 推薦：base64.b64encode（） + requests json= 參數
  • ✅ JavaScript 推薦：Buffer.toString（'base64'）（不是 'base64url'）
  • ✅ curl 推薦：先把 Base64 寫入文件，再用 -d @file.json 引用
  • ✅ API易優勢：原生格式兼容、控制檯可查 request_id 反查日誌、不限併發
  • ✅ 聯繫支持：保留 request_id，可快速定位

九、總結

gemini-3-pro-image-preview 報 Base64 decoding failed 錯誤，99% 的情況都是客戶端請求構造問題，而非服務端故障。錯誤信息中的 /9j/4AAQSkZJ 已經告訴我們：起始字節是合法的 JPEG Base64，問題出在數據的中間環節——可能是前綴污染、換行污染、URL 編碼、URL-safe 字符或截斷。

按本文第三章的 5 步排查流程順序檢查，絕大多數問題都能在 5 分鐘內定位。複雜場景（如壓縮後仍超大、多圖組合、特殊編碼）可以參考第四章的三種語言完整示例，複製即可運行。

如果你正在爲多模態項目尋找穩定的 gemini-3-pro-image-preview 接入方案，API易 apiyi.com 提供完整的 Gemini 系列模型中轉，原生格式 100% 兼容（僅需替換 base_url）、不限併發（批量圖像編輯場景友好）、充值 100 美金送 10%（相當於官網 85 折）、國內人民幣充值（無需海外信用卡）、控制檯可通過 request_id 反查完整日誌（極大降低排查成本）。

🎯 下一步行動建議：把本文第三章的 5 步排查流程按順序走一遍。如果走完仍未解決，記錄 request_id，提交給 API易 apiyi.com 技術支持，附上你的請求體（隱去敏感信息），通常 1 小時內能給到精準的定位。

參考資料

  1. Google Gemini API 官方文檔：圖像理解與生成

    • 鏈接: ai.google.dev/gemini-api/docs/image-generation
    • 說明: inline_data / file_data 字段規範、mime_type 列表

  2. Gemini 3 Developer Guide：新模型遷移指南

    • 鏈接: ai.google.dev/gemini-api/docs/gemini-3
    • 說明: gemini-3-pro-image-preview 與舊模型差異

  3. RFC 4648 – The Base16， Base32， and Base64 Data Encodings：Base64 標準規範

    • 鏈接: datatracker.ietf.org/doc/html/rfc4648
    • 說明: §4 標準 Base64 vs §5 URL-safe Base64 的區別

  4. API易官網：Gemini / Claude / OpenAI 全系列中轉服務

    • 鏈接: apiyi.com
    • 說明: 原生格式兼容、不限併發、人民幣充值、充值 100 美金送 10%

作者: 技術團隊
最後更新: 2026-05-02
關於 API易: API易 apiyi.com 是專業的 AI 大模型 API 中轉服務商，提供 gemini-3-pro-image-preview、Claude Sonnet 4.5、Claude Opus 4.7、GPT 系列等全系列模型的穩定接入，完全兼容原生 Gemini/OpenAI/Anthropic 三種格式，控制檯支持 request_id 反查完整請求日誌，充值 100 美金贈送 10%（相當於官網 85 折），不限併發，技術支持響應快。

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts