Gemini 3 来了。请阅读开发者指南，开始使用我们迄今为止最先进的 AI 模型。

此页面由 Cloud Translation API 翻译。

Gemini 3 开发者指南

Gemini 3 是我们迄今为止最智能的模型系列，以先进的推理能力为基础。它旨在通过掌握智能体工作流、自主编码和复杂的多模态任务，将任何想法变为现实。本指南介绍了 Gemini 3 模型系列的主要功能，以及如何充分利用这些功能。

Gemini 3 Pro 默认使用动态思考来推理提示。如果不需要复杂的推理，您可以将模型的思维水平限制为 low，以获得更快、更低延迟的回答。

Python

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

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

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]"}]
    }]
  }'

探索

Gemini 3 Applet 概览

不妨探索我们的 Gemini 3 应用合集，了解该模型如何处理高级推理、自主编码和复杂的多模态任务。

认识一下 Gemini 3

Gemini 3 Pro 是新系列中的首款模型。gemini-3-pro-preview 最适合需要广泛的世界知识和跨模态的高级推理的复杂任务。

模型 ID	上下文窗口（入 / 出）	知识截点	定价（输入 / 输出）*
gemini-3-pro-preview	100 万 / 6.4 万	2025 年 1 月	2 美元 / 12 美元（<20 万个 token） 4 美元 / 18 美元（>20 万个 token）

* 价格按每 100 万个 token 计算。所列价格为标准文本价格；多模态输入费率可能会有所不同。

如需详细了解速率限制、批量价格和其他信息，请参阅模型页面。

Gemini 3 中的新 API 功能

Gemini 3 引入了新的参数，旨在让开发者更好地控制延迟时间、费用和多模态保真度。

思考等级

thinking_level 参数用于控制模型在生成回答之前进行内部推理过程的最大深度。Gemini 3 将这些级别视为相对的思考许可，而不是严格的令牌保证。如果未指定 thinking_level，Gemini 3 Pro 将默认为 high。

low：尽可能缩短延迟时间并降低费用。最适合简单的指令遵循、聊天或高吞吐量应用
medium：（即将推出），发布时不支持
high（默认）：最大限度地提高推理深度。模型可能需要更长时间才能生成第一个 token，但输出结果会经过更仔细的推理。

媒体分辨率

Gemini 3 通过 media_resolution 参数引入了对多模态视觉处理的精细控制。分辨率越高，模型读取细小文本或识别细微细节的能力就越强，但会增加令牌用量和延迟时间。media_resolution 参数用于确定为每个输入图片或视频帧分配的 token 数量上限。

现在，您可以为每个媒体部分单独设置分辨率，也可以通过 generation_config 全局设置分辨率，分辨率可设置为 media_resolution_low、media_resolution_medium 或 media_resolution_high。如果未指定，模型会根据媒体类型使用最佳默认值。

推荐设置

媒体类型	推荐设置	令牌数量上限	使用指南
图片	`media_resolution_high`	1120	建议用于大多数图片分析任务，以确保获得最佳质量。
PDF	`media_resolution_medium`	560	非常适合文档理解；质量通常在 `medium` 时达到饱和。增加到 `high` 很少能改进标准文档的 OCR 结果。
视频（常规）	`media_resolution_low`（或 `media_resolution_medium`）	70（每帧）	注意：对于视频，`low` 和 `medium` 设置的处理方式相同（70 个令牌），以优化上下文使用情况。这对于大多数动作识别和描述任务来说已经足够。
视频（文字较多）	`media_resolution_high`	280（每帧）	仅当用例涉及读取密集文本 (OCR) 或视频帧中的微小细节时才需要。

查看完整详情

Python

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

# The media_resolution parameter is currently only available in the v1alpha API version.
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"}
                )
            ]
        )
    ]
)

print(response.text)

JavaScript

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

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1alpha/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": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

温度

对于 Gemini 3，我们强烈建议将温度参数保留为默认值 1.0。

虽然之前的模型通常可以通过调整温度来控制创造性与确定性，但 Gemini 3 的推理能力已针对默认设置进行了优化。更改温度（将其设置为低于 1.0）可能会导致意外行为，例如循环或性能下降，尤其是在复杂的数学或推理任务中。

思路签名

Gemini 3 使用思维签名在 API 调用之间保持推理上下文。这些签名是模型内部思考过程的加密表示形式。为确保模型保持推理能力，您必须在请求中将这些签名原封不动地返回给模型：

函数调用（严格）：该 API 会对“当前回合”强制执行严格的验证。缺少签名会导致 400 错误。
文本/聊天：验证并非强制执行，但省略签名会降低模型的推理能力和回答质量。

函数调用（严格验证）

当 Gemini 生成 functionCall 时，它会依赖 thoughtSignature 在下一轮中正确处理工具的输出。“当前对话轮次”包括自上次标准用户 text 消息以来发生的所有模型 (functionCall) 和用户 (functionResponse) 步骤。

单次函数调用：functionCall 部分包含签名。您必须归还。
并行函数调用：只有列表中的第一个 functionCall 部分会包含签名。您必须按收到的确切顺序退回这些部件。
多步（顺序）：如果模型调用一个工具、接收结果，然后在同一轮中调用另一个工具，则两个函数调用都有签名。您必须返回历史记录中的所有累积签名。

文字和流式传输

对于标准聊天或文本生成，我们无法保证签名一定会显示。

非流式传输：响应的最终内容部分可能包含 thoughtSignature，但并非始终存在。如果返回了此类令牌，您应将其发送回去，以保持最佳性能。
流式传输：如果生成了签名，则该签名可能位于包含空文本部分的最终块中。确保您的流解析器即使在文本字段为空的情况下也会检查签名。

代码示例

多步骤函数调用（按顺序）

用户在一个回合中提出了需要两个单独步骤（查看航班 -> 预订出租车）的问题。

第 1 步：模型调用 Flight Tool。
模型返回签名 <Sig_A>

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

第 2 步：用户发送航班结果
我们必须发送回 <Sig_A>，以保持模型的思路。

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

第 3 步：模型调用出租车工具
模型通过 <Sig_A> 记住航班延误情况，现在决定预订出租车。它会生成一个新签名 <Sig_B>。

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

第 4 步：用户发送出租车结果
如需完成此轮对话，您必须发送整个链：<Sig_A> 和 <Sig_B>。

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

并行函数调用

用户询问：“查看巴黎和伦敦的天气。”模型在一个回答中返回了两个函数调用。

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

文本/上下文推理（无验证）

用户提出的问题需要进行上下文推理，但不能使用外部工具。虽然未经过严格验证，但包含签名有助于模型针对后续问题保持推理链。

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

从其他型号迁移

如果您要从其他模型（例如，Gemini 2.5）或注入并非由 Gemini 3 生成的自定义函数调用，您将无法获得有效的签名。

如需在这些特定场景中绕过严格验证，请使用以下特定虚拟字符串填充相应字段："thoughtSignature": "context_engineering_is_the_way_to_go"

使用工具生成结构化输出

Gemini 3 可让您将结构化输出与内置工具（包括依托 Google 搜索进行接地、网址上下文和代码执行）结合使用。

Python

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

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(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

REST

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": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

从 Gemini 2.5 迁移

Gemini 3 是我们迄今为止功能最强大的模型系列，与 Gemini 2.5 Pro 相比，性能有了显著提升。迁移时，请考虑以下事项：

思考：如果您之前使用复杂的提示工程（例如思维链）来强制 Gemini 2.5 进行推理，请尝试使用 Gemini 3 和 thinking_level: "high" 以及简化的提示。
温度设置：如果您的现有代码明确设置了温度（尤其是将温度设置为较低的值以获得确定性输出），我们建议您移除此参数并使用 Gemini 3 的默认值 1.0，以避免在处理复杂任务时出现潜在的循环问题或性能下降。
PDF 和文档理解：PDF 的默认 OCR 分辨率已更改。如果您之前依赖于密集文档解析的特定行为，请测试新的 media_resolution_high 设置，以确保准确性不受影响。
令牌消耗：迁移到 Gemini 3 Pro 默认设置可能会增加 PDF 的令牌用量，但会减少视频的令牌用量。如果请求现在因默认分辨率更高而超出上下文窗口，我们建议明确降低媒体分辨率。
图片分割：Gemini 3 Pro 不支持图片分割功能（返回对象的像素级遮罩）。对于需要原生图像分割的工作负载，我们建议继续使用关闭了思考功能的 Gemini 2.5 Flash 或 Gemini Robotics-ER 1.5。

OpenAI 兼容性

对于使用 OpenAI 兼容层的用户，标准参数会自动映射到 Gemini 等效参数：

reasoning_effort (OAI) 映射到 thinking_level (Gemini)。请注意，reasoning_effort 中等映射到 thinking_level 高。

提示最佳实践

Gemini 3 是一种推理模型，因此您需要改变提示方式。

精确的指令：输入提示应简洁明了。Gemini 3 最适合处理直接、清晰的指令。它可能会过度分析用于旧模型的冗长或过于复杂的提示工程技术。
输出详细程度：默认情况下，Gemini 3 的输出详细程度较低，更倾向于提供直接、高效的答案。如果您的使用情形需要更具对话性或“聊天”风格的角色，您必须在提示中明确引导模型（例如，“以友善健谈的助理的身份解释一下”）。
上下文管理：处理大型数据集（例如整本书、代码库或长视频）时，请将具体指令或问题放在提示末尾的数据上下文之后。在提问时，以“根据上述信息…”之类的短语开头，将模型的推理锚定到提供的数据。

如需详细了解提示设计策略，请参阅提示工程指南。

常见问题解答

Gemini 3 Pro 的知识截止日期是什么？Gemini 3 的知识截止日期为 2025 年 1 月。如需了解最新信息，请使用搜索基础工具。
上下文窗口有哪些限制？Gemini 3 Pro 支持 100 万个 token 的输入上下文窗口，输出最多可达 6.4 万个 token。
Gemini 3 Pro 是否有免费层级？您可以在 Google AI Studio 中免费试用该模型，但目前 Gemini API 中没有 gemini-3-pro-preview 的免费层级。
我的旧 thinking_budget 代码是否仍然有效？可以，为了实现向后兼容性，我们仍支持 thinking_budget，但建议您迁移到 thinking_level 以获得更可预测的性能。请勿在同一请求中同时使用这两个参数。
Gemini 3 是否支持 Batch API？可以，Gemini 3 支持批量 API。
是否支持上下文缓存？可以，Gemini 3 支持上下文缓存。启动缓存所需的最低 token 数为 2,048 个。
Gemini 3 支持哪些工具？Gemini 3 支持Google 搜索、文件搜索、代码执行和网址上下文。它还支持标准函数调用，以便您使用自己的自定义工具。请注意，Google 地图和电脑使用目前不受支持。

后续步骤

开始使用 Gemini 3 Cookbook
请参阅有关思考水平的专用 Cookbook 指南，了解如何从思考预算迁移到思考水平。