Gemini 3 Pro Image API invalid_argument 错误完整排查指南【2025年12月】

# 检查你使用的模型名称
model_name = "gemini-3-pro-image-preview"  # Gemini 3 图像模型
model_name = "gemini-2.5-flash"             # Gemini 2.5 模型

# Gemini 3 特有问题只会出现在以下模型中：
# - gemini-3-pro-preview
# - gemini-3-pro-image-preview
# - gemini-3-flash-preview

# 首次请求：生成图像
response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=["生成一只戴帽子的猫"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

# 重要：保存 thought_signature
# 它在响应的第一个 part 中
thought_signature = None
for part in response.candidates[0].content.parts:
    if hasattr(part, 'thought_signature') and part.thought_signature:
        thought_signature = part.thought_signature
        break

print(f"保存的签名: {thought_signature[:50]}...")  # 签名通常很长

# 第二轮请求：编辑图像
# 必须包含之前保存的 thought_signature
second_response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents=[
        {
            "role": "user",
            "parts": [
                {"text": "把猫的颜色改成橙色"},
                {"thought_signature": thought_signature}  # 关键！
            ]
        }
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

# 错误示例：同时使用两个参数
config = {
    "thinking_level": "medium",      # ❌ 不能同时使用
    "thinking_budget": 1024          # ❌
}

# 正确示例：只用其中一个
config = {
    "thinking_level": "medium"       # ✅ 推荐使用 thinking_level
}

# 或者
config = {
    "thinking_budget": 1024          # ✅ 更精细的控制
}

import openai

# 配置 laozhang.ai 端点
client = openai.OpenAI(
    api_key="your-laozhang-api-key",
    base_url="https://api.laozhang.ai/v1"
)

# 使用与 OpenAI 相同的调用方式
response = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=[
        {"role": "user", "content": "生成一张日落风景图"}
    ]
)

# 图像 URL 在响应中
print(response.choices[0].message.content)

import google.generativeai as genai
from google.generativeai import types
import time

class GeminiImageClient:
    def __init__(self, api_key: str):
        genai.configure(api_key=api_key)
        self.model = genai.GenerativeModel("gemini-3-pro-image-preview")
        self.thought_signatures = {}  # 存储每个会话的签名

    def generate_image(self, prompt: str, session_id: str = "default"):
        """首次生成图像"""
        try:
            # 检查是否有之前的签名
            signature = self.thought_signatures.get(session_id)

            contents = [{"text": prompt}]
            if signature:
                contents.append({"thought_signature": signature})

            response = self.model.generate_content(
                contents,
                generation_config=types.GenerateContentConfig(
                    response_modalities=["TEXT", "IMAGE"],
                    # 只用一个 thinking 参数
                    thinking_level="medium"
                )
            )

            # 保存新的签名
            self._save_signature(response, session_id)

            return self._extract_image(response)

        except Exception as e:
            return self._handle_error(e)

    def _save_signature(self, response, session_id: str):
        """提取并保存 thought_signature"""
        for part in response.candidates[0].content.parts:
            if hasattr(part, 'thought_signature') and part.thought_signature:
                self.thought_signatures[session_id] = part.thought_signature
                print(f"[INFO] 签名已保存 (session: {session_id})")
                break

    def _extract_image(self, response):
        """提取图像数据"""
        for part in response.candidates[0].content.parts:
            if hasattr(part, 'inline_data') and part.inline_data:
                return {
                    "success": True,
                    "image_data": part.inline_data.data,
                    "mime_type": part.inline_data.mime_type
                }
        return {"success": False, "error": "No image in response"}

    def _handle_error(self, error):
        """错误处理和建议"""
        error_msg = str(error)

        if "thought_signature" in error_msg:
            return {
                "success": False,
                "error": "thought_signature 缺失",
                "suggestion": "确保保存并传递了上一轮的签名"
            }
        elif "thinking_level" in error_msg or "thinking_budget" in error_msg:
            return {
                "success": False,
                "error": "thinking 参数冲突",
                "suggestion": "只使用 thinking_level 或 thinking_budget 其中一个"
            }
        elif "Content.parts" in error_msg:
            return {
                "success": False,
                "error": "内容为空",
                "suggestion": "确保 contents 列表包含有效内容"
            }
        else:
            return {"success": False, "error": error_msg}

# 使用示例
client = GeminiImageClient("your-api-key")

# 第一轮：生成图像
result1 = client.generate_image("一只戴帽子的猫咪", session_id="cat_edit")
print(result1)

# 第二轮：编辑图像（自动携带签名）
result2 = client.generate_image("把猫咪的帽子换成红色", session_id="cat_edit")
print(result2)

# 首次请求
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "生成一张日落风景图"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "thinkingLevel": "medium"
    }
  }'

# 注意：响应中会包含 thought_signature
# 在第二轮请求中需要将其包含在 parts 数组中

def validate_request(contents, config):
    """请求前的预防性检查"""
    errors = []

    # 检查 1: contents 不能为空
    if not contents or len(contents) == 0:
        errors.append("contents 不能为空")

    # 检查 2: thinking 参数不能同时使用
    if config.get("thinking_level") and config.get("thinking_budget"):
        errors.append("不能同时使用 thinking_level 和 thinking_budget")

    # 检查 3: 检查图像数据
    for content in contents:
        if isinstance(content, dict):
            for part in content.get("parts", []):
                if "inline_data" in part:
                    if not part["inline_data"].get("data"):
                        errors.append("inlineData.data 不能为空")
                    if not part["inline_data"].get("mime_type"):
                        errors.append("inlineData.mime_type 不能为空")

    return errors if errors else None