Interactions API 现已正式发布。我们建议使用此 API 来访问所有最新功能和模型。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gemini 3.5 Flash 的新功能

Gemini 3.5 Flash 已正式发布 (GA)，稳定可靠，可大规模用于生产。作为我们最智能的 Flash 模型，它在智能体执行、编码和长期任务方面大规模实现了持续的领先性能。

本指南概述了 Gemini 3.5 Flash 的改进、API 更改和迁移指南。

新建模型

模型	模型 ID	说明
Gemini 3.5 Flash	`gemini-3.5-flash`	我们最智能的模型，可在智能体和编码任务中实现持续的领先性能。

Gemini 3.5 Flash 支持 100 万个 token 的上下文窗口、最多 65,000 个输出 token、思考功能，以及与 Gemini 3 Flash 相同的工具和平台功能集。目前不支持 Computer Use。

如需了解完整规范，请参阅模型概览。如需了解价格，请参阅价格页面。

快速入门

本指南中的所有示例均使用 Interactions API。GenerateContent API 也受支持；相同的配置选项和建议也适用。

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain how parallel agentic execution works in three sentences."
)
print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Explain how parallel agentic execution works in three sentences.",
  });
  console.log(interaction.output_text);
}

main();

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.5-flash",
    "input": "Explain how parallel agentic execution works in three sentences."
  }'

行为更改

新的默认工作量级别：`medium`

默认思考工作量现在为 medium，已从 Gemini 3 Flash 预览版中的 high 更改。medium 在各种任务中都能产生非常好的结果，同时速度更快、成本效益更高。对于复杂问题，high 会鼓励模型进行更深入的思考。

工作量级别	适用情形
`minimal`	针对响应速度进行了优化。类似聊天的应用场景、快速的事实性答案、更简单的工具调用。
`low`	需要更低延迟和更少步骤的代码和智能体任务。也适用于需要一些思考的分析和写作任务。
`medium`（默认）	大多数任务的最佳质量。建议用于复杂的代码和智能体应用场景。
`high`	最大限度地提高模型的思考和使用工具的能力。最适合复杂的推理、困难的数学运算以及最困难的代码或智能体任务。允许扩展思考和函数调用。

如需替换默认值，请在配置中设置 thinking_level：

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Prove that the square root of 2 is irrational.",
    generation_config={"thinking_level": "high"},
)
print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Prove that the square root of 2 is irrational.",
    generationConfig: { thinkingLevel: "high" },
  });
  console.log(interaction.output_text);
}

main();

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.5-flash",
    "input": "Prove that the square root of 2 is irrational.",
    "generation_config": {"thinking_level": "high"}
  }'

下表显示了每个模型支持的思考级别：

思考级别	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite	Gemini 3 Flash	说明
`minimal`	支持	不支持	支持（默认）	支持	与大多数查询的“不思考”设置匹配。请注意，`minimal` 不保证思考功能处于关闭状态，模型可能会针对复杂任务进行非常少的推理。
`low`	支持	支持	支持	支持	最大限度地降低延迟时间和成本。
`medium`	支持（默认）	支持	支持	支持	针对大多数任务进行平衡思考。
`high`	支持（动态）	支持（默认、动态）	支持（动态）	支持（默认、动态）	最大限度地提高推理深度。

思考保留

模型会自动在多轮对话中保留中间推理。如果对话记录中存在推理上下文，则推理上下文会延续下去，从而提高复杂的多步任务（例如迭代调试和代码重构）的性能。无需更改 API：

Interactions API：思考功能已自动保留。行为没有变化。
GenerateContent API：从 Gemini 3.5 Flash 开始，如果对话记录中存在思考特征，模型会使用之前所有轮次的推理上下文。如需启用此功能，请在 contents 中传递完整、未修改的对话记录（包括思考特征）。 SDK 会自动处理此问题。

Gemini 3.x 中的参数更新和最佳实践

以下内容适用于所有 Gemini 3.x 模型，包括 Gemini 3.5 Flash。

temperature、top_p、top_k ：我们强烈建议不要更改默认值。Gemini 3 的推理能力针对默认设置进行了优化。
使用 thinking_level 而不是 thinking_budget。
函数调用响应匹配：id、name 和响应计数必须与之前的调用匹配。
多模态函数响应：在函数响应内（而不是外部）添加多模态内容。
函数响应中的内嵌说明：附加到函数响应文本，而不是作为单独的部分。
减少不必要的工具调用：使用较低的思考级别或尝试使用系统说明，以减少智能体工作流中的工具调用。

如需了解如何更新代码，请参阅以下部分。

采样参数（不再推荐）

不再建议所有 Gemini 3.x 模型使用 temperature、top_p 和 top_k。Gemini 3 的推理能力针对默认设置进行了优化。从所有请求中移除这些参数。

# ⚠️ Remove these parameters (not recommended)
generation_config = {
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
}

为确保确定性，我们建议为您的特定应用场景定义包含明确规则的系统说明。

`thinking_budget`（不再推荐）

不再建议所有 Gemini 3.x 模型使用原始数值 thinking_budget 参数。请改用 thinking_level 字符串枚举。

# ⚠️ Before (not recommended)
generation_config = {
    "thinking": {"thinking_budget": 7500},
}

# ✅ After
generation_config = {
    "thinking": {"thinking_level": "medium"},
}

可用值：minimal、low、medium（默认）和 high。

函数调用：严格的响应匹配

Interactions API 已经针对不匹配的函数响应返回错误。GenerateContent API 尚未返回错误，但在大多数情况下，不匹配的响应会导致模型返回空响应，并显示 finish_reason: STOP。请始终遵循以下惯例：

要求	详细信息
添加 `id`	每个 `FunctionResponse` 都必须包含相应 `FunctionCall` 中的 `id`
匹配 `name`	响应中的 `name` 必须与调用中的 `name` 匹配
匹配计数	为收到的每个 `FunctionCall` 返回一个 `FunctionResponse`

Python

# ✅ Include matching call_id and name in the function_result
final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
)

JavaScript

// ✅ Include matching call_id and name in the function_result
const finalInteraction = await client.interactions.create({
  model: "gemini-3.5-flash",
  previousInteractionId: interaction.id,
  tools: [myTool],
  input: [{
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: JSON.stringify(result) }],
  }],
});

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.5-flash",
    "previous_interaction_id": "<INTERACTION_ID>",
    "tools": [...],
    "input": [{
      "type": "function_result",
      "name": "my_function",
      "call_id": "<CALL_ID>",
      "result": [{"type": "text", "text": "..."}]
    }]
  }'

多模态函数响应

我们经常看到客户端在函数响应之外提供图片。这可能会导致意外的模型行为（例如思考泄露），并导致输出质量降低。请改用多模态函数响应 API 文档中的建议，并在发送给模型的函数响应部分中添加多模态内容。模型可以在下一轮对话中处理此多模态内容，从而生成更明智的回答。

Python

# ✅ Include multimodal content in the function response
final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": tool_call.name,
            "call_id": tool_call.id,
            "result": [
                {"type": "text", "text": "instrument.jpg"},
                {
                    "type": "image",
                    "mime_type": "image/jpeg",
                    "data": base64_image_data,
                },
            ],
        }
    ],
)

JavaScript

// ✅ Include multimodal content in the function response
const finalInteraction = await client.interactions.create({
  model: "gemini-3.5-flash",
  previousInteractionId: interaction.id,
  input: [{
    type: "function_result",
    name: toolCall.name,
    call_id: toolCall.id,
    result: [
      { type: "text", text: "instrument.jpg" },
      {
        type: "image",
        mime_type: "image/jpeg",
        data: base64ImageData,
      },
    ],
  }],
});

函数响应中的内嵌说明

我们经常看到客户端将其他说明与函数响应一起作为后续 Parts 提供。这可能会导致意外的模型行为（例如思考泄露），并导致输出质量降低。请改为将任何额外的说明附加到函数响应文本的末尾，并用两个换行符分隔。

Python

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": result_text}],
    }],
)

JavaScript

// ✅ Append inline instructions to the end of the function response separated by two newlines
const resultText = `${JSON.stringify(result)}\n\n<your inline instructions>`;

const finalInteraction = await client.interactions.create({
  model: "gemini-3.5-flash",
  previousInteractionId: interaction.id,
  tools: [myTool],
  input: [{
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: resultText }],
  }],
});

减少不必要的工具调用

如果您发现工具调用过多，可以使用以下两种方法来最大限度地减少工具调用：

首先降低思考级别 （medium、low 或 minimal）：较高的思考级别会鼓励模型使用更多工具进行探索和验证，因此降低级别可以减少工具调用。
添加系统说明 ：如果在调整思考级别后工具调用过多问题仍然存在，请考虑使用限制工具使用的提示。例如：
```
You have a limited action budget of <n> tool calls. Use them efficiently.
```

迁移核对清单

我们强烈建议您更新到 google-genai SDK v2.0.0 或更高版本。此版本对 Interactions API 引入了重大更改。如需了解详情，请参阅重大更改迁移指南。

从 Gemini 3 Flash 预览版迁移

更新模型名称：gemini-3-flash-preview → gemini-3.5-flash
查看价格。Gemini 3.5 Flash 比 Gemini 3 Flash 预览版更贵。如果您的应用场景对成本非常敏感，请考虑改为迁移到 Gemini 3.1 Flash-Lite 。如需了解详情，请参阅价格页面。
从配置中移除 temperature、top_p、top_k（不再推荐）。
将 thinking_budget 替换为 thinking_level。
向所有 FunctionResponse 部分添加 id 和匹配的 name。
测试您的提示。默认工作量已从 high 更改为 medium；验证质量、速度和成本。
思考保留功能现在默认处于开启状态。推理上下文会在轮次之间延续，这会提高性能，但可能会增加 token 使用量。
减少不必要的工具调用：首先降低思考级别（medium、low 或 minimal）；如果工具调用过多问题仍然存在，请添加系统说明以限制工具使用。
Computer Use 目前在 Gemini 3.5 Flash 中不受支持。对于 Computer Use 工作负载，请继续使用 Gemini 3 Flash 预览版。

从 Gemini 2.5 迁移

除了上述内容之外，还包括：

简化提示。如果您之前使用思维链提示工程来强制推理，请尝试使用 thinking_level: "medium" 或 "high" 以及更简单的提示。
测试 PDF 和媒体工作负载。如果您之前依赖特定行为进行密集文档解析，请测试 media_resolution_high 设置，以确保准确率不受影响。迁移到 Gemini 3 默认设置也可能会增加 PDF 的 token 使用量，但会减少视频的 token 使用量；如果请求超出上下文窗口，请明确降低 media_resolution。如需了解详情，请参阅媒体分辨率文档。
利用组合工具使用。 Google 搜索、网址上下文、代码执行和自定义函数可以在同一请求中使用。
如果使用多模态函数响应，请将多模态内容移到函数响应部分内，而不是与函数响应部分并列。
如果将内嵌说明与函数响应一起使用，请将内嵌说明附加到函数响应文本的末尾，并用两个换行符分隔，而不是作为单独的部分。
Gemini 3.x 不支持图像分割。对于分割工作负载，请继续使用 Gemini 2.5 Flash（关闭思考功能）或 Gemini Robotics-ER 1.6。
从配置中移除 candidate_count（Gemini 3.x 不支持）

Gemini 3 系列功能

Gemini 3.5 Flash 继承了 Gemini 3 系列的所有功能，但 Computer Use 除外。 Gemini 3 中引入的功能如下：

思考：加密的推理上下文会在 API 调用之间保留。在 Interactions API 中自动保留；在 GenerateContent 中隐式保留。
使用工具的结构化输出: 将 JSON 模式与内置工具（搜索、网址上下文、代码执行、函数调用）相结合。
多模态函数响应：在函数调用结果中返回图片、音频和其他媒体。
代码执行与图片：执行处理和生成图片的代码。
组合工具使用: 在同一请求中使用内置工具和自定义函数调用。
媒体分辨率: 对图片、视频和 PDF 输入的 token 分配进行精细控制。 Gemini 3 模型支持针对混合保真度提示设置每个内容项的分辨率（low、 medium、high、ultra_high）。
思考特征：模型内部推理的加密表示形式。在无状态模式下进行多轮函数调用时需要；由 Interactions API 和官方 SDK 自动管理。

提示最佳实践

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

精确说明 ：应简明扼要。Gemini 3.x 最适合响应直接、清晰的说明。为旧模型设计的冗长或复杂的提示工程技术可能会导致模型过度分析。
输出详细程度 ：默认情况下，Gemini 3 和 3.1 的详细程度较低，更倾向于直接、高效的答案。如果您的应用场景需要对话语气，请在提示中明确引导模型（例如，“以友好健谈的助理身份解释此内容”）。
上下文管理 ：处理大型数据集（例如整本书、代码库或长视频）时，请将具体说明或问题放在提示的末尾，即数据上下文之后。通过以“根据上述信息…”等短语开头来锚定模型的推理。

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

限制

Gemini 3.x 不支持图像分割。对于分割工作负载，请继续使用 Gemini 2.5 Flash（关闭思考功能）或 Gemini Robotics-ER 1.6。

常见问题解答

Gemini 3.5 Flash 的知识截点是什么？Gemini 3.5 Flash 的知识截点为 2025 年 1 月。如需了解最新信息，请使用 Search Grounding 工具。
上下文窗口有哪些限制？Gemini 3.5 Flash 支持 100 万个 token 的输入上下文窗口，以及最多 65,000 个输出 token。
我的旧 thinking_budget 代码是否仍然有效？是的，thinking_budget 仍然受支持，以实现向后兼容性，但我们建议迁移到 thinking_level 以获得更可预测的性能。请勿在同一请求中同时使用这两者。
Gemini 3.5 Flash 是否支持 Batch API？是的。如需了解详情，请参阅 Batch API 指南。
是否支持上下文缓存？是的，支持上下文缓存。
支持哪些工具？Gemini 3.5 Flash 支持 Google 搜索、 Grounding with Google Maps、文件搜索、代码执行、网址上下文和标准函数调用，包括组合工具使用。Gemini 3.5 Flash 不支持 Computer Use。

后续步骤

如需详细了解提示设计策略，请参阅提示工程指南。
开始使用Gemini 3 Cookbook
了解 Gemini API 优化和推理

Gemini 3.5 Flash 的新功能

新建模型

快速入门

Python

JavaScript

REST

最新资讯

选择合适的 Flash 模型

行为更改

新的默认工作量级别：`medium`

Python

JavaScript

REST

思考保留

Gemini 3.x 中的参数更新和最佳实践

采样参数（不再推荐）

`thinking_budget`（不再推荐）

函数调用：严格的响应匹配

Python

JavaScript

REST

多模态函数响应

Python

JavaScript

函数响应中的内嵌说明

Python

JavaScript

减少不必要的工具调用

迁移核对清单

从 Gemini 3 Flash 预览版迁移

从 Gemini 2.5 迁移

Gemini 3 系列功能

提示最佳实践

限制

常见问题解答

后续步骤

Gemini 3.5 Flash 的新功能

新建模型

快速入门

Python

JavaScript

REST

最新资讯

选择合适的 Flash 模型

行为更改

新的默认工作量级别：medium

Python

JavaScript

REST

思考保留

Gemini 3.x 中的参数更新和最佳实践

采样参数（不再推荐）

thinking_budget（不再推荐）

函数调用：严格的响应匹配

Python

JavaScript

REST

多模态函数响应

Python

JavaScript

函数响应中的内嵌说明

Python

JavaScript

减少不必要的工具调用

迁移核对清单

从 Gemini 3 Flash 预览版迁移

从 Gemini 2.5 迁移

Gemini 3 系列功能

提示最佳实践

限制

常见问题解答

后续步骤

新的默认工作量级别：`medium`

`thinking_budget`（不再推荐）