Gemini API 联网搜索使用指南

原生 generateContent + google_search 工具即可联网，默认分组 KEY 直接可用，三个 Gemini 模型实测通过；OpenAI 兼容模式不支持，附判别方法与计费说明（$14/1K 次）。

本文说明在 API易 上使用 Gemini 系列模型实现联网搜索（Grounding with Google Search）的方法，基于 2026年6月 实测验证（3 模型 × 2 模式 × 多种工具声明，21 条请求证据）。Gemini 原生格式的基础接入请先看 Gemini 原生调用。

​

一句话结论

API易 Gemini 原生端点完整支持 Google 官方联网搜索：使用 /v1beta generateContent + google_search 工具，gemini-3.5-flash、gemini-3.1-flash-lite、gemini-3.1-pro-preview 实测均真实联网、返回带来源引用的最新信息。默认分组的 KEY 即可使用，无需任何特殊开通。

端点：   POST https://api.apiyi.com/v1beta/models/{模型名}:generateContent
工具：   tools: [{"google_search": {}}]
模型：   gemini-3.5-flash / gemini-3.1-flash-lite / gemini-3.1-pro-preview（实测验证）

OpenAI 兼容模式（/v1/chat/completions）不支持联网搜索。实测 web_search_options、透传 google_search、tools: [{"type": "web_search"}] 三种声明全部返回 HTTP 200 但被静默忽略——模型只是凭训练数据回答。请不要以”没报错”判断联网已生效，判别方法见下文。

​

真实可用性（实测数据，2026-06-11）

模型	联网结果	groundingMetadata	单次问答搜索次数	延迟
gemini-3.5-flash	✅ 当周真实新闻，多查询交叉检索	✅ 完整	4–7 次	24–45s
gemini-3.1-flash-lite	✅ 当周真实新闻	✅（偶发缺失，见注意事项）	2 次	~5s
gemini-3.1-pro-preview	✅ 当周真实新闻，深思考后精准检索	✅	1 次	~45s

选型建议：对延迟敏感、高频调用选 gemini-3.1-flash-lite（约 5 秒）；追求检索广度和答案质量选 gemini-3.5-flash（多查询交叉验证，thinking 消耗大、延迟高，见计费一节）。

​

快速上手

​

cURL

curl "https://api.apiyi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "content-type: application/json" \
  -H "x-goog-api-key: 你的APIYI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "过去一周 AI 领域有什么重要新闻？请搜索后列出 3 条并附来源网址。"}]}],
    "generationConfig": {"maxOutputTokens": 4096},
    "tools": [{"google_search": {}}]
  }'

​

Python（google-genai SDK）

from google import genai
from google.genai import types

client = genai.Client(
    api_key="你的APIYI_KEY",                      # 默认分组即可
    http_options={"base_url": "https://api.apiyi.com"},  # 注意：不带 /v1
)

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="过去一周 AI 领域有什么重要新闻？请搜索后列出 3 条并附来源网址。",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
        max_output_tokens=4096,
    ),
)

# 1) 最终回答文本
print(resp.text)

# 2) 联网证据：实际执行的搜索词与来源
gm = resp.candidates[0].grounding_metadata
if gm:
    print("搜索词:", gm.web_search_queries)
    for chunk in gm.grounding_chunks or []:
        print("来源:", chunk.web.title, chunk.web.uri)
else:
    print("⚠️ 本次未触发联网搜索")

​

怎么确认搜索真的执行了

成功联网时，响应 candidates[0].groundingMetadata 包含以下字段；没有这些字段就是没搜：

字段	含义
webSearchQueries	模型实际执行的搜索词数组（数组长度 = 搜索次数）
groundingChunks	检索到的来源（URI + 标题）
groundingSupports	回答正文片段与来源的对应关系（startIndex/endIndex）
searchEntryPoint	渲染 Google 搜索建议所需的 HTML/CSS

对照参考：同一问题不带工具时，模型一致回答”知识截止 2025年1月，无法提供最新信息”；带工具后准确给出训练截止之后发生的真实事件。

​

计费说明（重要）

联网搜索会收取工具调用费用，由两部分组成：

项目	价格	说明
工具调用费	$14 / 1000 次（$0.014/次）	工具名：google_search；按实际执行的搜索次数计费，即 groundingMetadata.webSearchQueries 数组长度——一次提问可能触发多次搜索（实测 pro-preview 1 次、flash-lite 2 次、3.5-flash 4–7 次）
模型 token 费	按模型标准价	与 OpenAI 联网不同，检索内容不注入 input token（实测联网前后 promptTokenCount 几乎不变，31–43 token）；大头是 thinking + output token（3.5-flash 一次深度联网问答消耗 thoughts 3500–4900 token，按 output 价计费）

单次联网问答总开销参考（搜索费 + token 费）：flash-lite ≈ $0.03；3.5-flash ≈ $0.08–0.16；3.1-pro-preview ≈ $0.06。如需控制成本，可在提示词中约束搜索行为（如”最多搜索 2 次”），或选用搜索次数少的模型。

可能享受免费减免：Gemini API 官方为联网搜索提供一定免费配额（Gemini 3 系列每月 5,000 条提示免费，超出后按 $14/1K 次计）。上游命中免费配额时，该次搜索费可获减免（实测出现过整次未扣搜索费的情况）；有扣费则按上表价格正常计费。实际以控制台计费明细为准。

​

注意事项

1. 必须走原生端点：OpenAI 兼容模式的所有搜索声明都被静默忽略且不报错。用 OpenAI SDK 的项目改用 google-genai SDK（base_url 设为 https://api.apiyi.com，不带 /v1）即可。
2. 以 groundingMetadata 为准判断联网：实测 flash-lite 偶发（4 次中 1 次）不返回 groundingMetadata。严格场景请校验该字段存在性，缺失时重试。
3. 思考型模型给足 maxOutputTokens（建议 ≥4096）：3.5-flash / 3.1-pro-preview 联网时 thinking 消耗 1900–4900 token，上限过小会截断回答。
4. 工具声明 {"google_search": {}} 与 camelCase {"googleSearch": {}} 均可用；旧版 google_search_retrieval 是 Gemini 1.5 时代的工具，当前模型一律用 google_search。
5. 联网搜索可与 URL Context 等工具组合使用（Google 官方文档：ai.google.dev/gemini-api/docs/google-search）。

​

FAQ

Q：怎么确认这次回答真的联网了？

A：检查 candidates[0].groundingMetadata 是否存在、webSearchQueries 是否非空、groundingChunks 是否包含来源 URI。只有正文、没有这些字段的，是模型凭训练数据回答。

Q：需要换分组或特殊 KEY 吗？

A：不需要。Gemini 系列模型使用默认分组的 KEY 即可直接调用联网搜索（与 OpenAI 联网搜索一致；区别于 Claude 原生搜索需要 ClaudeOfficial 内测分组）。

Q：搜索次数怎么看、不同模型差异大吗？

A：数 groundingMetadata.webSearchQueries 数组长度。同一问题实测差异很大：pro-preview 1 次、flash-lite 2 次、3.5-flash 4–7 次。

Q：支持哪些模型？

A：gemini-3.5-flash、gemini-3.1-flash-lite、gemini-3.1-pro-preview 已实测验证。其他 Gemini 2.5+ 模型理论上同样支持 google_search 工具，使用前建议按上面 FAQ 的方法做一次验证。

​

相关文档

Gemini 原生调用

google-genai SDK 配置、流式输出、thinking 控制

Gemini Function Calling

自定义工具调用，可与联网搜索组合使用