Gemini 3 开发者指南

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

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

只需几行代码，即可开始使用：

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(interaction.steps[-1].content[0].text)

JavaScript

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

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(interaction.steps.at(-1).content[0].text);
}

run();

REST

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

认识 Gemini 3 系列

Gemini 3.1 Pro 最适合处理需要广泛的世界知识和跨模态高级推理的复杂任务。

Gemini 3 Flash 是我们最新的 3 系列模型，具有 Pro 级智能，但速度和价格与 Flash 相当。

Nano Banana Pro（也称为 Gemini 3 Pro Image）是我们质量最高的图片生成模型，而 Nano Banana 2（也称为 Gemini 3.1 Flash Image）则是高容量、高效率、低价位的同类产品。

Gemini 3.1 Flash-Lite 是我们专为经济高效的模型和高容量任务打造的主力模型。

所有 Gemini 3 模型目前都处于预览版阶段。

模型 ID 上下文窗口（输入 / 输出） 知识截点 定价（输入 / 输出）*
gemini-3.1-flash-lite-preview 100 万 / 6.4 万 2025 年 1 月 $0.25（文本、图片、视频），$0.50（音频）/ $1.50
gemini-3.1-flash-image-preview 12.8 万 / 3.2 万 2025 年 1 月 $0.25（文本输入）/ $0.067（图片输出）**
gemini-3.1-pro-preview 100 万 / 6.4 万 2025 年 1 月 $2 / $12（<20 万个 token）
$4 / $18（>20 万个 token）
gemini-3-flash-preview 100 万 / 6.4 万 2025 年 1 月 $0.50 / $3
gemini-3-pro-image-preview 6.5 万 / 3.2 万 2025 年 1 月 $2（文本输入）/ $0.134（图片输出）**

* 除非另有说明，否则价格按每 100 万个 token 计算。 ** 图片定价因分辨率而异。如需了解详情，请参阅价格页面。

如需了解详细的限制、定价和其他信息，请参阅 模型页面。

Gemini 3 中的新 API 功能

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

思考等级

Gemini 3 系列模型默认使用动态思考来对提示进行推理。您可以使用 thinking_level 参数，该参数用于控制模型在生成回答之前执行的内部推理过程的最大 深度。Gemini 3 将这些等级视为思考的相对配额，而不是严格的 token 保证。

如果未指定 thinking_level，Gemini 3 将默认为 high。如果不需要复杂的推理，您可以将模型的思考等级限制为 low，以获得更快、延迟更低的回答。

思考等级 Gemini 3.1 Pro Gemini 3.1 Flash-Lite Gemini 3 Flash 说明
minimal 不支持 受支持（默认） 受支持 与大多数查询的“不思考”设置相匹配。对于复杂的编码任务，模型可能会进行非常少的思考。最大限度地缩短聊天或高吞吐量应用的延迟时间。注意，minimal 并不能保证思考功能处于关闭状态。
low 受支持 支持 受支持 最大限度地缩短延迟时间和降低费用。最适合简单的指令遵循、聊天或高吞吐量应用。
medium 受支持 支持 受支持 针对大多数任务进行平衡思考。
high 受支持（默认、动态） 受支持（动态） 受支持（默认、动态） 最大限度地提高推理深度。模型可能需要更长的时间才能 生成第一个（非思考）输出 token，但输出将经过更仔细的推理。

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="How does AI work?",
    generation_config={"thinking_level": "low"},
)

print(interaction.steps[-1].content[0].text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "How does AI work?",
    generationConfig: {
      thinking_level: "low",
    },
  });

console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "input": "How does AI work?",
    "config": {
      "thinking_level": "low"
    }
  }'

温度

对于所有 Gemini 3 模型，我们强烈建议将温度参数保持在默认值 1.0。

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

思考签名

Gemini 3 模型使用思考签名在 API 调用之间保持推理上下文。这些签名是模型内部思考过程的加密表示形式。

  • 有状态模式（推荐）：在有状态模式下（提供 previous_interaction_id）使用 Interactions API 时，服务器会自动管理对话历史记录和思考签名。
  • 无状态模式：如果您手动管理对话历史记录，则必须在后续请求中包含思考块及其签名，以验证真实性。

如需了解详细信息，请参阅思考签名页面。

图片生成和修改

对于 gemini-3-pro-image-preview 和 gemini-3.1-flash-image-preview，思考签名对于对话式智能修图至关重要。当您要求模型修改图片时，它会依赖于上一轮的 signature 来了解原始图片的构图和逻辑。

  • 修改： 签名保证在回答的思考（text 或 inlineData）之后的第一部分以及每个后续 inlineData 部分中。您必须返回所有这些签名，以避免错误。

代码示例

多步骤函数调用（顺序）

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

第 1 步：模型调用航班工具。
模型返回签名 <Sig_A>

// Model Response (Turn 1, Step 1)
  {
    "id": "interaction-123",
    "steps": [
      {
        "type": "function_call",
        "name": "check_flight",
        "arguments": {"flight": "AA100"},
        "signature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

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

// User Request (Turn 1, Step 2)
  {
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "interaction-123",
    "input": [
      {
        "type": "function_result",
        "call_id": "fc_check_flight",
        "name": "check_flight",
        "result": [{ "type": "text", "text": "{\"status\": \"delayed\", \"departure_time\": \"12 PM\"}" }]
      }
    ]
  }

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

// Model Response (Turn 1, Step 3)
  {
    "id": "interaction-123",
    "steps": [
      {
        "type": "function_call",
        "name": "book_taxi",
        "arguments": {"time": "10 AM"},
        "signature": "<Sig_B>" // SAVE THIS
      }
    ]
  }

第 4 步：用户发送出租车结果
如需完成这一轮，您必须发回整个链：<Sig_A> AND <Sig_B>。

// User Request (Turn 1, Step 4)
  {
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "interaction-123",
    "input": [
      {
        "type": "function_result",
        "call_id": "fc_book_taxi",
        "name": "book_taxi",
        "result": [{ "type": "text", "text": "{\"booking_status\": \"success\"}" }]
      }
    ]
  }

并行函数调用

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

// Model Response
  {
    "id": "interaction-456",
    "steps": [
      {
        "type": "function_call",
        "name": "check_weather",
        "arguments": { "city": "Paris" },
        "signature": "<Signature_A>" // INCLUDED on First FC
      },
      {
        "type": "function_call",
        "name": "check_weather",
        "arguments": { "city": "London" }
      }
    ]
  }

// User Request (Sending Parallel Results)
  {
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "interaction-456",
    "input": [
      {
        "type": "function_result",
        "call_id": "fc_paris",
        "name": "check_weather",
        "result": [{ "type": "text", "text": "15C" }]
      },
      {
        "type": "function_result",
        "call_id": "fc_london",
        "name": "check_weather",
        "result": [{ "type": "text", "text": "12C" }]
      }
    ]
  }

从其他模型迁移

如果您要从其他模型（例如 Gemini 2.5）转移对话跟踪记录，或者注入并非由 Gemini 3 生成的自定义函数调用，则不会获得有效的签名。

如需在这些特定场景中绕过严格的验证，请使用 以下特定虚拟字符串填充该字段："signature": "context_engineering_is_the_way to_go"

使用工具的结构化输出

Gemini 3 模型允许您将 结构化输出 与内置工具相结合，包括 依托 Google 搜索进行接地、网址上下文、代码执行和函数调用。

Python

from google import genai
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()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Search for all details for the latest Euro.",
    tools=[
        {"type": "google_search"},
        {"type": "url_context"}
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": MatchResult.model_json_schema()
    },
)

result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const matchJsonSchema = {
  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"]
};

const matchSchema = z.fromJSONSchema(matchJsonSchema);

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "Search for all details for the latest Euro.",
    tools: [
      { type: "google_search" },
      { type: "url_context" }
    ],
    response_format: {
        type: "text",
        mime_type: "application/json",
        schema: matchJsonSchema
    },
  });

  const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
  console.log(match);
}

run();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "input": "Search for all details for the latest Euro.",
    "tools": [
      {"type": "google_search"},
      {"type": "url_context"}
    ],
    "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "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 3.1 Flash Image 和 Gemini 3 Pro Image，您可以根据文本提示生成和修改图片。它使用推理来“思考”提示，并且可以在生成高保真图片之前检索实时数据（例如天气预报或股票图表），然后再使用 Google 搜索 建立依据。

新增和改进的功能：

  • 4K 和文本呈现： 生成清晰易读的文本和图表，分辨率高达 2K 和 4K。
  • 接地生成： 使用 google_search 工具验证事实，并根据真实世界的信息生成图片。Gemini 3.1 Flash Image 支持使用 Google 图片搜索进行接地。
  • 对话式智能修图： 只需提出更改要求（例如“将背景设为日落”），即可进行多轮图片修改。此工作流依赖于思考签名 来保留轮次之间的视觉上下文。

如需详细了解宽高比、修改工作流和配置 选项，请参阅图片生成指南。

Python

from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-pro-image-preview",
    input="Generate an infographic of the current weather in Tokyo.",
    tools=[{"type": "google_search"}],
    response_format={
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "4K"
    }
)

from PIL import Image
import io

image_blocks = [content_block for content_block in interaction.steps[-1].content if content_block.type == "image"]
if image_blocks:
    image_data = base64.b64decode(image_blocks[0].data)
    image = Image.open(io.BytesIO(image_data))
    image.save('weather_tokyo.png')
    image.show()

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3-pro-image-preview",
    input: "Generate a visualization of the current weather in Tokyo.",
    tools: [{ googleSearch: {} }],
    responseFormat: {
      type: "image",
      aspectRatio: "16:9",
      imageSize: "4K"
    }
  });

  for (const contentBlock of interaction.steps.at(-1).content) {
    if (contentBlock.type === "image") {
      const buffer = Buffer.from(contentBlock.data, "base64");
      fs.writeFileSync("weather_tokyo.png", buffer);
    }
  }
}

run();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "input": "Generate a visualization of the current weather in Tokyo.",
    "tools": [{"type": "google_search"}],
    "response_format": {
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "4K"
    }
  }'

示例响应

东京天气

使用图片的代码执行

Gemini 3 Flash 可以将视觉视为主动调查，而不仅仅是静态浏览。通过将推理与 代码执行相结合，模型会制定计划，然后编写并执行 Python 代码，逐步放大、剪裁、添加注释或以其他方式处理图片，以直观地接地回答。

用例：

  • 缩放和检查： 模型会隐式检测到细节过小（例如读取远处仪表或序列号），并编写代码来裁剪和重新检查该区域，以获得更高的分辨率。
  • 视觉数学和绘图： 模型可以使用代码运行多步骤计算（例如对收据上的行项目求和，或根据提取的数据生成 Matplotlib 图表）。
  • 图片注释： 模型可以直接在图片上绘制箭头、边界框或其他注释，以回答“此商品应放在哪里？”等空间问题。

如需启用视觉思考，请将 代码执行 配置为工具。模型会在需要时自动使用代码来处理图片。

Python

from google import genai
from google.genai import types
import requests
from PIL import Image
import io
import base64

image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        image,
        "Zoom into the expression pedals and tell me how many pedals are there?"
    ],
    tools=[{"code_execution": {}}],
)

from IPython.display import display
from PIL import Image
import io

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                 display(Image.open(io.BytesIO(base64.b64decode(content_block.data))))
    elif step.type == "code_execution_call":
        print(step.code)
    elif step.type == "code_execution_result":
        print(step.output)

JavaScript

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

const client = new GoogleGenAI({});

async function main() {
  const imageUrl = "https://goo.gle/instrument-img";
  const response = await fetch(imageUrl);
  const imageArrayBuffer = await response.arrayBuffer();
  const base64ImageData = Buffer.from(imageArrayBuffer).toString("base64");

  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      {
        inlineData: {
          mime_type: "image/jpeg",
          data: base64ImageData,
        },
      },
      {
        text: "Zoom into the expression pedals and tell me how many pedals are there?",
      },
    ],
    tools: [{ codeExecution: {} }],
  });

  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content) {
        if (contentBlock.type === "text") {
          console.log("Text:", contentBlock.text);
        }
      }
    } else if (step.type === "code_execution_call") {
      console.log("Code:", step.code);
    } else if (step.type === "code_execution_result") {
      console.log("Output:", step.output);
    }
  }
}

main();

REST

IMG_URL="https://goo.gle/instrument-img"
MODEL="gemini-3-flash-preview"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "'$MODEL'",
      "input": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"'"$MIME_TYPE"'",
                "data": "'"$IMAGE_B64"'"
              }
            },
            {"text": "Zoom into the expression pedals and tell me how many pedals are there?"}
        ]
      }],
      "tools": [{"code_execution": {}}]
    }'

如需详细了解使用图片的代码执行，请参阅代码执行。

多模态函数响应

多模态函数调用 允许用户获得包含 多模态对象的函数响应，从而更好地利用模型的函数调用 功能。标准函数调用仅支持基于文本的函数响应：

Python 

from google import genai
import requests
import base64

client = genai.Client()

# 1. Define the tool
get_image_tool = {
    "type": "function",
    "name": "get_image",
    "description": "Retrieves the image file reference for a specific order item.",
    "parameters": {
        "type": "object",
        "properties": {
            "item_name": {
                "type": "string",
                "description": "The name or description of the item ordered (e.g., 'instrument')."
            }
        },
        "required": ["item_name"],
    },
}

# 2. Send the request with tools
interaction_1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Show me the instrument I ordered last month.",
    tools=[get_image_tool],
)

# 3. Find the function call step
fc_step = next(s for s in interaction_1.steps if s.type == "function_call")
print(f"Tool Call: {fc_step.name}({fc_step.arguments})")

# Execute tool (fetch image)
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image_b64 = base64.b64encode(image_bytes).decode("utf-8")

# 4. Send multimodal function result back
interaction_2 = client.interactions.create(
    model="gemini-3-flash-preview",
    previous_interaction_id=interaction_1.id,
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [
            {"type": "text", "text": "instrument.jpg"},
            {
                "type": "image",
                "mime_type": "image/jpeg",
                "data": image_b64,
            }
        ]
    }],
    tools=[get_image_tool]
)

print(f"\nFinal model response: {interaction_2.steps[-1].content[0].text}")

JavaScript 

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

const client = new GoogleGenAI({});

// 1. Define the tool
const getImageTool = {
    type: 'function',
    name: 'get_image',
    description: 'Retrieves the image file reference for a specific order item.',
    parameters: {
        type: 'object',
        properties: {
            item_name: {
                type: 'string',
                description: "The name or description of the item ordered (e.g., 'instrument').",
            },
        },
        required: ['item_name'],
    },
};

// 2. Send the request with tools
const interaction1 = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Use the get_image tool to show me the instrument I ordered last month.',
    tools: [getImageTool],
});

// 3. Find the function call step
const fcStep = interaction1.steps.find(s => s.type === 'function_call');
console.log(`Tool Call: ${fcStep.name}(${JSON.stringify(fcStep.arguments)})`);

// Execute tool (fetch image)
const imageUrl = 'https://goo.gle/instrument-img';
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');

// 4. Send multimodal function result back
const interaction2 = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    previous_interaction_id: interaction1.id,
    input: [{
        type: 'function_result',
        name: fcStep.name,
        call_id: fcStep.id,
        result: [
            { type: 'text', text: 'instrument.jpg' },
            {
                type: 'image',
                mime_type: 'image/jpeg',
                data: base64ImageData,
            }
        ]
    }],
    tools: [getImageTool]
});

console.log(`\nFinal model response: ${interaction2.steps.at(-1).content[0].text}`);

REST 

IMG_URL="https://goo.gle/instrument-img"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

# Check for macOS
if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

# 1. First interaction (triggers function call)
# curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
#   -H "x-goog-api-key: $GEMINI_API_KEY" \
#   -H 'Content-Type: application/json' \
#   -d '{ "model": "gemini-3-flash-preview", "input": "Show me the instrument I ordered last month.", "tools": [...] }'

# 2. Send multimodal function result back (Replace INTERACTION_ID and CALL_ID)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "INTERACTION_ID",
    "input": [{
      "type": "function_result",
      "name": "get_image",
      "call_id": "CALL_ID",
      "result": [
        { "type": "text", "text": "instrument.jpg" },
        {
          "type": "image",
          "mime_type": "'"$MIME_TYPE"'",
          "data": "'"$IMAGE_B64"'"
        }
      ]
    }]
  }'

结合使用内置工具和函数调用

Gemini 3 允许在同一 API 调用中使用内置工具（例如 Google 搜索、网址 上下文等）和自定义 函数调用 工具，从而实现 更复杂的工作流。

Python

from google import genai
from google.genai import types

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"type": "google_search"},
        getWeather
    ],
)

# Find the function call step
fc_step = next((s for s in interaction.steps if s.type == "function_call"), None)

if fc_step:
    # Simulate a function result
    result = {"response": "Very cold. 22 degrees Fahrenheit."}

    final_interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input=[
            {"type": "function_result", "name": fc_step.name, "call_id": fc_step.id, "result": result}
        ],
        tools=[
            {"type": "google_search"},
            getWeather
        ],
        previous_interaction_id=interaction.id,
    )

    print(final_interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

const client = new GoogleGenAI({});

const getWeatherDeclaration = {
  type: 'function',
  name: 'getWeather',
  description: 'Gets the weather for a requested city.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      city: {
        type: Type.STRING,
        description: 'The city and state, e.g. Utqiaġvik, Alaska',
      },
    },
    required: ['city'],
  },
};

const interaction = await client.interactions.create({
  model: 'gemini-3-flash-preview',
  input: "What is the northernmost city in the United States? What's the weather like there today?",
  tools: [
    { type: "google_search" },
    getWeatherDeclaration
  ],
});

// Find the function call step
const fcStep = interaction.steps.find(s => s.type === 'function_call');

if (fcStep) {
  const result = { response: "Very cold. 22 degrees Fahrenheit." };

  const finalInteraction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: [
      { type: 'function_result', name: fcStep.name, call_id: fcStep.id, result: result }
    ],
    tools: [
      { type: "google_search" },
      getWeatherDeclaration
    ],
    previous_interaction_id: interaction.id,
  });

  console.log(finalInteraction.steps.at(-1).content[0].text);
}

从 Gemini 2.5 迁移

Gemini 3 是我们迄今为止功能最强大的模型系列，与 Gemini 2.5 相比，它在各个方面都有所改进。迁移时，请考虑以下事项：

  • 思考： 如果您之前使用复杂的提示工程（例如 思路链）来强制 Gemini 2.5 进行推理，请尝试使用 Gemini 3 和 thinking_level: "high" 以及简化的提示。
  • 温度设置： 如果现有代码明确设置了温度（尤其是设置为较低值以实现确定性输出），我们建议移除此参数并使用 Gemini 3 的默认值 1.0，以避免在处理复杂任务时出现潜在的循环问题或性能下降。
  • PDF 和文档理解： 如果您之前依赖特定行为进行密集文档解析，请测试新的 media_resolution_high 设置，以确保准确率不受影响。
  • token 消耗： 迁移到 Gemini 3 默认设置可能会增加 PDF 的 token 使用量，但会减少 视频的 token 使用量。如果请求现在因默认分辨率较高而超出上下文窗口，我们建议明确降低媒体分辨率。
  • 图像分割： Gemini 3 Pro 或 Gemini 3 Flash 不支持图像分割功能（返回对象的像素级掩码）。对于 需要内置图像分割功能的工作负载，我们建议继续 使用 Gemini 2.5 Flash 并关闭思考功能，或者使用 Gemini Robotics-ER 1.6。
  • 计算机使用： Gemini 3 Pro 和 Gemini 3 Flash 支持计算机 使用。与 2.5 系列不同，您无需使用单独的模型即可访问计算机使用工具。
  • 工具支持：Gemini 3 模型现在支持将内置工具与函数调用相结合。地图 接地现在还支持 Gemini 3 模型。

OpenAI 兼容性

对于使用 OpenAI 兼容性层 的用户， 标准参数（OpenAI 的 reasoning_effort）会自动映射到 Gemini (thinking_level) 等效项。

提示最佳实践

Gemini 3 是一个推理模型，这会改变您提示的方式。

  • 精确的说明： 输入提示应简洁明了。Gemini 3 最适合直接、清晰的说明。它可能会过度分析用于旧模型的冗长或过于复杂的提示工程技术。
  • 输出详细程度： 默认情况下，Gemini 3 不太冗长，更倾向于提供直接、高效的回答。如果您的应用场景需要更口语化或更“健谈”的角色设定，您必须在提示中明确引导模型（例如，“以友好健谈的助理身份解释此内容”）。
  • 上下文管理： 处理大型数据集（例如整本书、 代码库或长视频）时，请将具体说明或问题放在提示的 末尾，即数据上下文之后。通过以“根据前面的信息…”之类的短语开头提问，将模型的推理锚定到提供的数据。

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

常见问题解答

  1. Gemini 3 的知识截点是什么？Gemini 3 模型的知识截点为 2025 年 1 月。如需了解最新信息，请使用 搜索接地工具。

  2. 上下文窗口有哪些限制？Gemini 3 模型支持 100 万个 token 输入的上下文窗口，以及支持最多 64,000 个 token 输出。

  3. Gemini 3 是否有免费层级？Gemini API 中提供了 Gemini 3 Flash gemini-3-flash-preview 的免费层级。您可以在 Google AI Studio 中免费试用 Gemini 3.1 Pro 和 3 Flash，但 Gemini API 中没有 gemini-3.1-pro-preview 的免费层级。

  4. 我的旧 thinking_budget 代码是否仍然有效？是的，thinking_budget 仍然受支持，以实现向后兼容，但我们建议您迁移到 thinking_level，以获得更可预测的性能。请勿在同一请求中同时使用这两者。

  5. Gemini 3 是否支持 Batch API？是的，Gemini 3 支持 Batch API。

  6. 是否支持上下文缓存？是的，上下文缓存支持 Gemini 3。

  7. Gemini 3 支持哪些工具？Gemini 3 支持 Google 搜索、 Grounding with Google Maps、 文件搜索、 代码执行和 网址上下文。它还支持 标准 函数调用，用于 您自己的自定义工具，并可 与内置工具结合使用。

  8. gemini-3.1-pro-preview-customtools 是什么？如果您使用的是 gemini-3.1-pro-preview，并且模型忽略了您的自定义工具而改用 bash 命令，请尝试改用 gemini-3.1-pro-preview-customtools 模型。 详见此处。

后续步骤