解決 Gemini 圖片模型報錯 required oneof field data 的 6 種常見原因和修復方法

作者注：詳解調用 gemini-3.1-flash-image-preview 等 Gemini 圖片模型時出現 required oneof field data must have one initialized field 400 錯誤的 6 種常見原因和對應修復方案

調用 gemini-3.1-flash-image-preview（Nano Banana 2）或 gemini-3.0-pro-image（Nano Banana Pro）生成圖片時，不少開發者遇到了這個讓人困惑的 400 錯誤：

{
  "status_code": 400，
  "error": {
    "message": "* GenerateContentRequest.contents[0].parts[2].data: required oneof field 'data' must have one initialized field"，
    "type": "upstream_error"，
    "code": 400
  }
}

這個報錯的核心含義是：你發送的請求體中，某個 parts 元素的 data 字段爲空或格式不正確。400 錯誤屬於客戶端請求參數錯誤，不會自動恢復，必須修復代碼才能解決。

本文梳理了導致這個報錯的 6 種常見原因，每種都附上了錯誤代碼 vs 正確代碼的對比，幫你快速定位並修復問題。

核心價值: 讀完本文，你可以根據報錯信息中的 parts[N] 索引號精準定位問題位置，對照 6 種原因逐一排查，通常 5 分鐘內即可修復。

Gemini 圖片模型報錯 required oneof field data 核心分析

要點	說明	排查方向
報錯本質	`parts` 數組中存在空的或格式錯誤的元素	檢查 `contents[].parts[]` 每個元素
關鍵線索	`parts[2]` 表示第 3 個元素（從 0 計數）	直接定位到對應索引的 part
錯誤類型	400 INVALID_ARGUMENT，客戶端錯誤	不會自動恢復，必須改代碼
影響範圍	所有 Gemini 圖片模型通用	NB2、NB Pro、Gemini Flash 均適用
修復難度	低，通常是格式問題	對照正確格式修改即可

Gemini 圖片模型報錯信息結構解讀

先來拆解報錯信息的結構，這是定位問題的關鍵：

GenerateContentRequest.contents[0].parts[2].data
                       ^^^^^^^^     ^^^^^^^^
                       │            │
                       │            └── 第 3 個 part（索引從 0 開始）
                       └── 第 1 個 content 塊

contents[0]：指向你請求體中的第 1 個 content 對象
parts[2]：指向該 content 中的第 3 個 part 元素
data：該 part 的數據字段爲空或未正確初始化

排查思路：直接檢查你代碼中 contents 數組第 [0] 個元素的 parts 數組第 [2] 個元素，看它到底傳了什麼。

Gemini 圖片模型報錯 6 種常見原因和修復方法

原因 1：parts 中存在空對象或空字符串

這是最常見的原因。 請求的 parts 數組中混入了 {}、null、空字符串 "" 等空值元素。

錯誤寫法	正確寫法
`parts` 中包含 `{}` 空對象	每個 part 必須有 `text` 或 `inlineData`
`parts` 中包含 `{"text": ""}`	空文本也會觸發錯誤，至少寫一個字符
`parts` 中包含 `null` 元素	移除所有 `null` 值

錯誤代碼：

# ❌ parts 中有空對象
payload = {
    "contents": [{
        "parts": [
            {"text": "Generate a cat image"}，
            {}，                              # ← 空對象，觸發報錯
            {"text": "in watercolor style"}
        ]
    }]
}

正確代碼：

# ✅ 每個 part 都有有效內容
payload = {
    "contents": [{
        "parts": [
            {"text": "Generate a cat image in watercolor style"}
        ]
    }]
}

修復要點：合併文本到一個 text part 中，或確保每個 part 都包含有效的 text 或 inlineData 字段。

原因 2：圖片 base64 數據爲空或格式錯誤

當你發送圖生圖（image-to-image）請求時，inlineData 中的 base64 數據可能爲空、損壞或格式不正確。

錯誤代碼：

# ❌ base64 數據包含了 data URI 前綴
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png"，
                    "data": "data:image/png；base64，iVBORw0KGgo..."  # ← 不應包含前綴
                }
            }，
            {"text": "Change the background to blue"}
        ]
    }]
}

# ❌ base64 數據爲空字符串
"inlineData": {
    "mimeType": "image/jpeg"，
    "data": ""          # ← 空數據，直接觸發報錯
}

正確代碼：

import base64
import pathlib

# ✅ 正確讀取圖片並轉爲純 base64
image_bytes = pathlib.Path（"input.png"）.read_bytes（）
image_b64 = base64.b64encode（image_bytes）.decode（"utf-8"）

payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png"，
                    "data": image_b64       # ← 純 base64 字符串，無前綴
                }
            }，
            {"text": "Change the background to blue"}
        ]
    }]
}

修復要點：

data 字段只接受純 base64 字符串，不能包含 data:image/png；base64， 前綴
確保圖片文件真實存在且讀取成功，避免傳入空字符串
mimeType 必須與實際圖片格式匹配（image/png、image/jpeg、image/webp）

原因 3：File 對象未正確轉換爲內容引用

使用 Google GenAI SDK 的 Files API 上傳文件後，直接將 File 對象傳入 contents 可能導致 SDK 無法正確轉換。

錯誤代碼：

from google import genai

client = genai.Client（api_key="YOUR_KEY"）

# 上傳文件
file = client.files.upload（file="photo.png"）

# ❌ 某些 SDK 版本下直接傳 File 對象會失敗
response = client.models.generate_content（
    model="gemini-3.1-flash-image-preview"，
    contents=["Edit this image"， file]    # ← File 對象可能無法自動轉換
）

正確代碼：

from google import genai
from google.genai import types

client = genai.Client（api_key="YOUR_KEY"）

# 上傳文件
file = client.files.upload（file="photo.png"）

# ✅ 方法 1：手動構建文件引用
response = client.models.generate_content（
    model="gemini-3.1-flash-image-preview"，
    contents=[
        types.Content（parts=[
            types.Part（file_data=types.FileData（file_uri=file.uri， mime_type=file.mime_type）），
            types.Part（text="Edit this image: change background to sunset"）
        ]）
    ]，
    config=types.GenerateContentConfig（
        response_modalities=["TEXT"， "IMAGE"]
    ）
）

# ✅ 方法 2：改用 inlineData 直接傳 base64（更可靠）
import base64， pathlib

image_b64 = base64.b64encode（pathlib.Path（"photo.png"）.read_bytes（））.decode（）

response = client.models.generate_content（
    model="gemini-3.1-flash-image-preview"，
    contents=[
        types.Content（parts=[
            types.Part（inline_data=types.Blob（mime_type="image/png"， data=image_b64）），
            types.Part（text="Edit this image: change background to sunset"）
        ]）
    ]，
    config=types.GenerateContentConfig（
        response_modalities=["TEXT"， "IMAGE"]
    ）
）

修復要點：推薦使用 inlineData + base64 的方式直接傳圖片數據，比 Files API 更穩定可靠。

原因 4：多輪對話歷史中包含空內容

在多輪對話編輯圖片時，如果上一輪的響應沒有正確處理，對話歷史中可能混入空的 content 塊。

錯誤代碼：

# ❌ 對話歷史中混入了空 parts
history = [
    {"role": "user"， "parts": [{"text": "Generate a logo"}]}，
    {"role": "model"， "parts": []}，        # ← 空 parts，觸發報錯
    {"role": "user"， "parts": [{"text": "Make it blue"}]}
]

payload = {"contents": history}

正確代碼：

# ✅ 過濾掉空的 content 塊
history = [
    {"role": "user"， "parts": [{"text": "Generate a logo"}]}，
    {"role": "model"， "parts": [{"text": "Here is the logo I generated."}]}，
    {"role": "user"， "parts": [{"text": "Make it blue"}]}
]

# 安全過濾：移除 parts 爲空的記錄
clean_history = [msg for msg in history if msg.get（"parts"） and len（msg["parts"]） > 0]

payload = {"contents": clean_history}

修復要點：在發送請求前，遍歷 contents 數組，過濾掉所有 parts 爲空列表或包含空對象的元素。

原因 5：REST API 請求中 JSON 字段名大小寫錯誤

Gemini API 的 JSON 字段名使用 camelCase（駝峯命名），大小寫敏感。字段名拼錯會導致該字段被忽略，等同於傳了空數據。

錯誤字段名	正確字段名	說明
`inline_data`	`inlineData`	REST API 用 camelCase
`mime_type`	`mimeType`	REST API 用 camelCase
`file_uri`	`fileUri`	REST API 用 camelCase
`response_modalities`	`responseModalities`	REST API 用 camelCase
`image_config`	`imageConfig`	REST API 用 camelCase
`aspect_ratio`	`aspectRatio`	REST API 用 camelCase
`image_size`	`imageSize`	REST API 用 camelCase

錯誤代碼：

# ❌ REST API 中使用了 snake_case（Python SDK 風格）
payload = {
    "contents": [{
        "parts": [{
            "inline_data": {           # ← 應該是 inlineData
                "mime_type": "image/png"，   # ← 應該是 mimeType
                "data": image_b64
            }
        }]
    }]，
    "generation_config": {             # ← 應該是 generationConfig
        "response_modalities": ["IMAGE"]   # ← 應該是 responseModalities
    }
}

正確代碼：

# ✅ REST API 使用 camelCase
payload = {
    "contents": [{
        "parts": [{
            "inlineData": {
                "mimeType": "image/png"，
                "data": image_b64
            }
        }]
    }]，
    "generationConfig": {
        "responseModalities": ["IMAGE"]，
        "imageConfig": {
            "aspectRatio": "1:1"，
            "imageSize": "2K"
        }
    }
}

🎯 易混淆提醒: Python SDK（google-genai）使用 snake_case（如 inline_data），而直接調用 REST API 使用 camelCase（如 inlineData）。通過 API易 apiyi.com 等中轉平臺調用時，使用的是 REST API 格式，必須用 camelCase。

原因 6：圖片格式不支持或文件損壞

傳入的圖片雖然有 base64 數據，但圖片本身格式不受支持或文件已損壞。

Gemini 圖片模型支持的輸入格式：

格式	mimeType	支持狀態
PNG	`image/png`	支持
JPEG	`image/jpeg`	支持
WebP	`image/webp`	支持
GIF	`image/gif`	部分支持（僅首幀）
BMP	`image/bmp`	不支持
SVG	`image/svg+xml`	不支持
TIFF	`image/tiff`	不支持

排查方法：

import base64

# 檢查 base64 數據是否有效
def validate_image_data（b64_string， mime_type）:
    # 1. 檢查是否爲空
    if not b64_string:
        print（"ERROR: base64 data is empty"）
        return False

    # 2. 檢查是否包含 data URI 前綴
    if b64_string.startswith（"data:"）:
        print（"ERROR: Remove 'data:image/...；base64，' prefix"）
        return False

    # 3. 檢查 base64 是否可解碼
    try:
        decoded = base64.b64decode（b64_string）
        print（f"OK: Decoded size = {len（decoded）} bytes"）
    except Exception as e:
        print（f"ERROR: Invalid base64 - {e}"）
        return False

    # 4. 檢查 mimeType 是否受支持
    supported = ["image/png"， "image/jpeg"， "image/webp"， "image/gif"]
    if mime_type not in supported:
        print（f"ERROR: Unsupported mimeType '{mime_type}'"）
        return False

    print（"PASS: Image data is valid"）
    return True

💡 建議: 在發送請求前加上數據校驗函數，可以提前捕獲大部分格式問題。通過 API易 apiyi.com 平臺調用時同樣適用。

Gemini 圖片模型報錯完整排查清單

當你遇到 required oneof field 'data' 報錯時，按以下清單逐項排查：

排查步驟	檢查內容	修復方法
Step 1	看 `parts[N]` 中的 N 是第幾個元素	直接定位到代碼中對應位置
Step 2	該 part 是否爲 `{}`、`null`、`""`	移除空元素或填充有效內容
Step 3	若是 `inlineData`，base64 是否爲空	確保圖片文件讀取成功
Step 4	base64 是否包含 `data:` 前綴	去掉前綴，只保留純 base64
Step 5	JSON 字段名是否用了 camelCase	REST API 必須用 `inlineData` 而非 `inline_data`
Step 6	圖片格式是否受支持	僅 PNG/JPEG/WebP/GIF

快速修復: 如果你在開發階段頻繁遇到此錯誤，建議在請求發送前添加一個 validate_payload（） 函數，自動檢查 parts 數組中的每個元素是否有效。通過 API易 apiyi.com 平臺調用 Gemini 圖片模型時，請求格式與官方 REST API 完全一致，上述排查方法同樣適用。

Gemini 圖片模型報錯正確請求格式參考

純文生圖（Text-to-Image）正確格式

import requests， base64

API_KEY = "your-apiyi-api-key"
ENDPOINT = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"

# ✅ 最簡正確格式
payload = {
    "contents": [{
        "parts": [
            {"text": "A cute orange cat sitting on a windowsill， watercolor style， 4K"}
        ]
    }]，
    "generationConfig": {
        "responseModalities": ["IMAGE"]，
        "imageConfig": {
            "aspectRatio": "1:1"，
            "imageSize": "2K"
        }
    }
}

response = requests.post（
    ENDPOINT，
    headers={"Content-Type": "application/json"， "x-goog-api-key": API_KEY}，
    json=payload，
    timeout=120
）

result = response.json（）
image_data = result["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
with open（"output.png"， "wb"） as f:
    f.write（base64.b64decode（image_data））

圖生圖（Image-to-Image）正確格式

查看圖生圖完整正確代碼

import requests
import base64
import pathlib

API_KEY = "your-apiyi-api-key"
ENDPOINT = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"

# 讀取原圖並轉爲純 base64
image_path = pathlib.Path（"input_photo.png"）
if not image_path.exists（）:
    raise FileNotFoundError（f"Image not found: {image_path}"）

image_bytes = image_path.read_bytes（）
image_b64 = base64.b64encode（image_bytes）.decode（"utf-8"）

# 驗證數據
assert len（image_b64） > 0， "Base64 data is empty"
assert not image_b64.startswith（"data:"）， "Remove data URI prefix"

# ✅ 正確的圖生圖請求格式
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png"，
                    "data": image_b64
                }
            }，
            {
                "text": "Change the background to a sunset beach scene， keep the subject unchanged"
            }
        ]
    }]，
    "generationConfig": {
        "responseModalities": ["IMAGE"]，
        "imageConfig": {
            "aspectRatio": "1:1"，
            "imageSize": "2K"
        }
    }
}

response = requests.post（
    ENDPOINT，
    headers={"Content-Type": "application/json"， "x-goog-api-key": API_KEY}，
    json=payload，
    timeout=120
）

if response.status_code == 200:
    result = response.json（）
    output_data = result["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
    with open（"output_edited.png"， "wb"） as f:
        f.write（base64.b64decode（output_data））
    print（"Success！ Image saved."）
else:
    print（f"Error {response.status_code}: {response.text}"）

建議: 文生圖場景建議從最簡格式開始，確認能跑通後再逐步添加參數。通過 API易 apiyi.com 平臺調用 Nano Banana 2，按次計費 $0.045/次，調試階段的成本非常低。

常見問題

Q1: 報錯信息中 parts[2] 是什麼意思？

parts[2] 表示 parts 數組中索引爲 2 的元素，即第 3 個元素（索引從 0 開始）。直接在你的代碼中定位到 contents[0].parts 數組的第 3 個元素，檢查它的內容即可。如果你的 parts 數組只有 2 個元素（索引 0 和 1），那說明代碼邏輯中可能在拼接 parts 時意外添加了一個空元素。

Q2: 通過 API易調用時也會遇到這個錯誤嗎？

會的。API易 apiyi.com 作爲中轉平臺，會將你的請求透傳給 Gemini 後端。如果請求體本身有格式問題，後端會返回相同的 400 錯誤。API易不會修改你的請求體結構，所以確保請求格式正確是開發者的責任。好消息是，修復方法和直接調用 Google API 完全相同。

Q3: Python SDK 和 REST API 的字段名爲什麼不一樣？

Google GenAI Python SDK 遵循 Python 的 snake_case 命名慣例（如 inline_data、mime_type），SDK 內部會自動轉換爲 API 要求的 camelCase。但如果你直接用 requests 庫調用 REST API（包括通過 API易 apiyi.com 調用），必須手動使用 camelCase 格式（如 inlineData、mimeType），否則字段會被忽略導致報錯。

Q4: 這個錯誤和 contents.parts must not be empty 是同一個嗎？

不完全相同，但原因類似。contents.parts must not be empty 是 parts 數組本身爲空（"parts": []），而 required oneof field 'data' 是 parts 中存在元素但該元素的數據字段未初始化（如 "parts": [{}]）。修復思路一致：確保每個 part 都包含有效的 text 或 inlineData。

總結

Gemini 圖片模型 required oneof field 'data' 報錯的核心要點：

根本原因：parts 數組中存在空對象、空數據或格式錯誤的元素
定位方法：根據報錯中的 parts[N] 索引號直接定位到代碼中的對應位置
最常見原因：空對象 {}、base64 含 data: 前綴、JSON 字段名大小寫錯誤
REST API 必須用 camelCase：inlineData（非 inline_data）、mimeType（非 mime_type）
預防措施：發送前添加 payload 校驗函數，自動檢測空元素和格式問題

推薦通過 API易 apiyi.com 平臺調用 Gemini 圖片模型進行開發調試，Nano Banana 2 按次計費 $0.045/次，調試成本極低，接口格式與官方 REST API 完全兼容。

📚 參考資料

Gemini API 圖像生成官方文檔: 完整的請求格式和參數說明
- 鏈接: ai.google.dev/gemini-api/docs/image-generation
- 說明: 包含 Text-to-Image 和 Image-to-Image 的標準請求格式
Gemini API 錯誤排查指南: 官方提供的錯誤代碼和修復建議
- 鏈接: ai.google.dev/gemini-api/docs/troubleshooting
- 說明: 涵蓋 400、429、500 等常見錯誤的排查方法
GitHub Issue: required oneof field data 錯誤討論: 社區報告和修復方案
- 鏈接: github.com/google-gemini/cookbook/issues/786
- 說明: 包含 File 對象傳遞導致此錯誤的詳細分析和 workaround
API易 Nano Banana 2 接入文檔: API易平臺調用 Gemini 圖片模型的完整指南
- 鏈接: docs.apiyi.com/en/api-capabilities/nano-banana-2-image
- 說明: 包含正確的請求格式示例和常見問題解答

作者: APIYI 技術團隊
技術交流: 遇到 Gemini API 調用問題，歡迎訪問 API易 docs.apiyi.com 文檔中心查看更多排錯指南

解決 Gemini 圖片模型報錯 required oneof field data 的 6 種常見原因和修復方法

Gemini 圖片模型報錯 required oneof field data 核心分析

Gemini 圖片模型報錯信息結構解讀

Gemini 圖片模型報錯 6 種常見原因和修復方法

原因 1：parts 中存在空對象或空字符串

原因 2：圖片 base64 數據爲空或格式錯誤

原因 3：File 對象未正確轉換爲內容引用

原因 4：多輪對話歷史中包含空內容

原因 5：REST API 請求中 JSON 字段名大小寫錯誤

原因 6：圖片格式不支持或文件損壞

Gemini 圖片模型報錯完整排查清單

Gemini 圖片模型報錯正確請求格式參考

純文生圖（Text-to-Image）正確格式

圖生圖（Image-to-Image）正確格式

常見問題

總結

📚 參考資料

Higgsfield AI Nano Banana Pro 圖像生成 API 調用指南: 5 種方案對比,最低 2 折獲取 4K 圖像

解讀 Gemini 3.1 Pro Preview 上線: 3 個核心升級與 API 接入指南

3步完成 Google AI Studio 遷移到 API易：保留代碼僅改2處配置

解決 Sora 2 API 視頻時長報錯：seconds 參數 invalid_value 錯誤的 3 種修復方案

Nano Banana Pro 實測對比:Vertex AI vs AI Studio 的 5 大核心差異

解決 Gemini 3 Pro Image 503 錯誤的 5 種多模型備選方案實戰指南

Gemini 圖片模型報錯 required oneof field data 核心分析

Gemini 圖片模型報錯信息結構解讀

Gemini 圖片模型報錯 6 種常見原因和修復方法

原因 1：parts 中存在空對象或空字符串

原因 2：圖片 base64 數據爲空或格式錯誤

原因 3：File 對象未正確轉換爲內容引用

原因 4：多輪對話歷史中包含空內容

原因 5：REST API 請求中 JSON 字段名大小寫錯誤

原因 6：圖片格式不支持或文件損壞

Gemini 圖片模型報錯 完整排查清單

Gemini 圖片模型報錯 正確請求格式參考

純文生圖（Text-to-Image）正確格式

圖生圖（Image-to-Image）正確格式

常見問題

總結

📚 參考資料

Similar Posts

Gemini 圖片模型報錯完整排查清單

Gemini 圖片模型報錯正確請求格式參考