Gemini 3 API 文档

目录

• 模型概述
• 快速开始
• 核心api特性
• 从gemini-25迁移
• 提示词最佳实践
• 常见问题解答

模型概述

Gemini 3 是Google最智能的模型系列，基于先进的推理技术构建。

模型规格

参数	值
模型ID	gemini-3-pro-preview
上下文窗口	1M / 64k (输入/输出)
知识截止日期	2025年1月
定价	2美元 / 12美元 (<200k tokens) 4美元 / 18美元 (>200k tokens)

快速开始

Python SDK

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

JavaScript SDK

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

REST API

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

核心API特性

1. 思考等级 (thinking_level)

控制模型推理深度。

等级	描述	适用场景
low	最小化延迟和成本	简单指令遵循、聊天、高吞吐量应用
medium	即将推出	暂不支持
high	最大化推理深度（默认）	复杂任务，需要仔细推理

示例配置：

config = types.GenerateContentConfig(
    thinking_level="low"
)

⚠️ 警告：不能同时使用 thinking_level 和 thinking_budget

2. 媒体分辨率 (media_resolution)

控制多模态视觉处理的token分配。

分辨率设置：

• media_resolution_low
• media_resolution_medium
• media_resolution_high

推荐配置表：

媒体类型	推荐设置	Max Tokens	说明
图像	media_resolution_high	1120	大多数图像分析任务
PDF	media_resolution_medium	560	文档理解任务
视频(通用)	media_resolution_low	70/帧	动作识别、描述
视频(文本密集)	media_resolution_high	280/帧	OCR、细节识别

Python示例：

from google import genai
from google.genai import types
import base64

client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

3. 温度 (temperature)

• 推荐值: 1.0（默认）
• 注意: 降低温度可能导致意外行为

4. 思维签名 (thoughtSignature)

维护跨API调用的推理上下文。

关键规则：

• 必须将签名按原样返回
• 函数调用：严格验证，缺少签名报400错误
• 文本聊天：验证不强制，但影响性能

多步函数调用示例：

// 第1步：模型响应
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "check_flight", "args": {...} },
      "thoughtSignature": "<Sig_A>"
    }
  ]
}

// 第2步：用户请求（必须包含签名）
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>"
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

迁移解决方案：

"thoughtSignature": "context_engineering_is_the_way_to_go"

5. 结构化输出与工具结合

Python示例：

from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="获胜者名称")
    final_match_score: str = Field(description="最终比分")
    scorers: List[str] = Field(description="得分者列表")

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

从Gemini 2.5迁移

迁移指南

方面	建议
思考能力	使用 thinking_level: "high" + 简化提示词
温度设置	移除显式设置，使用默认值1.0
PDF处理	测试 media_resolution_high 确保精度
Token消耗	监控PDF(token↑)和视频(token↓)的变化
图像分割	继续使用Gemini 2.5 Flash

提示词最佳实践

核心原则

1. 精确指令 - 简洁直接的提示词效果最佳
2. 控制详细程度 - 默认简洁，需要时明确指定风格
3. 上下文管理 - 指令放在数据上下文之后

示例对比

# 推荐 - 简洁直接
"总结这篇文章的主要观点"

# 不推荐 - 过于复杂
"请使用链式思维推理方法，逐步分析这篇文章，首先...然后...最后..."

常见问题解答

❓ 知识截止日期？

答: 2025年1月，可使用搜索grounding获取更新信息

❓ 上下文窗口限制？

答: 100万token输入，64k token输出

❓ 有免费套餐吗？

答: Google AI Studio可免费试用，API无免费套餐

❓ thinking_budget还能用吗？

答: 支持但建议迁移到thinking_level

❓ 支持批量API吗？

答: 是的，支持批量API

❓ 支持上下文缓存吗？

答: 是的，最小2048token可启动缓存

❓ 支持哪些工具？

答:

• ✅ Google Search, File Search, Code Execution, URL Context
• ✅ 自定义函数调用
• ❌ Google Maps, Computer Use（暂不支持）

---

文档版本: 1.0
最后更新: 2025年
适用模型: gemini-3-pro-preview