Gemini API 是什么

Gemini API 是 Google 提供的模型调用接口：程序把文字、图片、音频或 PDF 发过去，模型把生成的文字发回来。它不是聊天产品，而是让程序用上 Gemini 的通道。（核验 2026-11-05，F1、F3、F40）

一、Gemini API 是什么：问题不是它会不会聊天，而是程序怎么用上模型

一句话：Gemini API 是让程序用上 Gemini 模型的接口。 模型本身跑在 Google 的服务器上，你的程序通过这个接口把内容送过去、把结果取回来。可以把它想成一个远程函数：输入是文字或图片，输出是一段文字。

为什么需要这么一层？人会打开网页、粘贴截图、问一句，这很容易。程序不会——它不会点输入框，也不会按发送。但客服系统要自动读工单截图、法务要批量过合同、运营要给几千条评论分类，这些都得让程序自己去做。API 就是给程序留的那个入口。

一次调用其实只有三样东西：

• 模型：这件事交给谁做。比如 gemini-3.8-flash，它在代码里只是一个字符串。
• 输入：你递进去的内容。一句话、一张截图、一份 PDF、一段录音都算。
• 输出：模型交回来的文字。程序里通常读 output_text（F9）。

它能做什么。 按输入分：读文字（问答、总结、改写、翻译）、看图（截图里的报错、票据、图表）、读文档（PDF 合同、扫描件）、听音频、看视频。按输出分：可以要自由文字，也可以要按你给的 JSON 结构返回；还可以让它调用你定义的函数，或者接 Google 搜索查实时信息。这里先给全貌，每一项怎么用分别在第 4、5、6、7、8 章。

它不能做什么。 这块比能力清单更重要，因为误解基本都出在这里。它不是聊天产品——聊天界面是 AI Studio，人和模型直接对话；API 是给程序用的。它不替你部署、不替你管登录和权限。它的输出是生成的，不保证事实正确，要可核验就得接检索并把引用位置展示出来（见 7.2）。免费层有限额，数据政策也和付费层不同（F19、F37）。另外，所在区域要在官方清单内：官方可用区域清单里没有中国大陆，官方建议这类需求走企业版渠道（F40，见 1.2）。

谁适合看。 要把模型能力接进自己系统的开发者；只想聊天的人，直接去 AI Studio 更快。

几个名词先对齐，后面就不容易被绕晕：

二、把一次调用拆成两半：最小可运行示例

看完上面那些，再看一次调用具体长什么样。下面这段代码把调用拆成请求和响应，让你看清三样东西分别放在哪里。它不联网、不需要密钥，用一个本地假接口返回固定文字。

## EXPECT: 请求 model=gemini-3.8-flash input=这段报错怎么修？ | 返回 output_text=先查配额，再重试
MODEL = "gemini-3.8-flash"
def build_request(text):
    return {"model": MODEL, "input": text}
def read_response(resp):
    return resp["output_text"]
def fake_api(request):
    return {"output_text": "先查配额，再重试", "model": request["model"]}
req = build_request("这段报错怎么修？")
resp = fake_api(req)
out = f"请求 model={req['model']} input={req['input']} | 返回 output_text={read_response(resp)}"
assert set(req) == {"model", "input"}
assert "output_text" in resp
print(out)

build_request 只放模型和输入，read_response 只取 output_text。这不是完整实现，是最小形状：字段名来自官方（F3、F9），但请求体的嵌套结构、多模态内容怎么摆、流式怎么接，要到见 2.2 才展开。fake_api 是本教程放的替身，让示例离线就能跑；真实调用要密钥，本节不碰。

三、解释与边界：从哪个名字开始写

知道了它是什么，下一个问题是代码里该写哪个名字。入门阶段最容易错的不是写不出代码，是把三个名字搞混。

第一个是包名，也就是 pip install 后面那串。官方现在给的是 Python 用 google-genai、JavaScript 用 @google/genai（F1）；google-generativeai 和 @google/generative-ai 已被明令禁用（F2）。抄到旧教程里那行 import google.generativeai，报的是 ImportError，不是环境坏了。

第二个是调用对象，也就是代码里那个名字。官方默认是 client.interactions（F3）；generateContent 还能用，但已经标成 legacy，意思是「暂时没关，别再照着新写」（F4）。这两个名字背后是两套写法，混着抄会出现「字段名对不上」的怪问题，而且不报错，只是取不到东西。

第三个是文档版本。官方每个文档页加 .md 后缀就能取到纯文本版，本教程的事实都从这个端点核（F5）。所以看到一篇教程既没写核验日期、又给了一堆价格和限额，先别急着信。

边界：本节不教怎么申请密钥、不教重试和超时、不碰真实网络。版本怎么选见 2.3，一次能塞多少内容见 9.3。

四、预期输出与异常分支：返回里有什么，哪里会错

在本地跑上面那段代码，输出是：

请求 model=gemini-3.8-flash input=这段报错怎么修？ | 返回 output_text=先查配额，再重试

读法很直白：请求里只有 model 和 input，返回里只有 output_text。真实响应还会带用量、结束原因、引用位置等字段，但程序最先关心的就是这一段文字。

三种常见错，症状都在代码里，原因都在名字上：

• ImportError: No module named 'google.generativeai'——包名用了废弃的（F2），换成 google-genai。
• KeyError: 'output_text'——不是模型没回答，是你读错了字段（F9），或者把 generateContent 的旧响应结构套了过来。
• 在产品页翻半天找不到 GEMINI_API_KEY——你在找 AI Studio 的入口，不是 API 的（F40）。

这三种都不是「模型不会用」，是入口和名字没对上。

五、判据卡：这件事该不该用 Gemini API

六、来源与核验：官方页与 F 编号

• https://aistudio.google.com/llms.txt（核验 2026-11-05，F1、F2、F3、F4、F5、F9）
• https://aistudio.google.com/docs/available-regions.md（核验 2026-11-05，F40）
• https://aistudio.google.com/docs/rate-limits.md（核验 2026-11-05，F19）
• https://aistudio.google.com/docs/pricing.md（核验 2026-11-05，F37）
• https://aistudio.google.com/docs/terms.md（核验 2026-11-05，F59，待核）

待核说明：网页版内容许可范围仍标为待核（F59）。本节只讲它是什么、能做什么、不能做什么，不对许可条款下断言；要引用或转载，请到官方页复核后自行判断。

七、动手试：三个可验收练习

1. 用一句话向同事解释「Gemini API 和 AI Studio 的区别」，不许出现「接口」「调用」这两个词。说不清，说明你记住的是术语，不是概念。
2. 把 fake_api 的返回改成 {"text": "先查配额，再重试"}，重跑。read_response 会抛 KeyError；写一句说明：为什么「改字段名」比「换模型」更常是故障原因。
3. 拿你手上那个想做的功能，用一句话写出它的「输入」和「输出各是什么」。写不出来，说明还没到写代码那一步。