Gemini API

Gemini API 是 Google 面向开发者提供的官方模型接口，可调用 Gemini 系列多模态模型完成文本、图像与文件理解等任务，并可通过 Google AI Studio 试用与调试后再接入代码。

这是什么

Gemini API 是 Google 面向开发者提供的官方接口，用来在自己的服务端调用 Gemini 系列模型。它和 Gemini 助手产品的关系与其他家一致：同一批模型，两套独立的使用方式与账单。

它有一个别家没有的入口优势：先在网页里调，再把调好的参数搬进代码。

从 AI Studio 拿密钥

新用户在 Google AI Studio 里会自动获得一个项目和一把 API Key，直接从密钥页复制即可，不需要先建项目、开服务、配权限。这是它对新手最友好的一点。

拿到之后按惯例存进环境变量：

export GEMINI_API_KEY="你的密钥"

需要付费额度时，在 AI Studio 里配置结算账号即可切换。

认证：请求头和别家不一样

REST 调用时，密钥不放在 Authorization 里，而是走一个自有的请求头：

x-goog-api-key: $GEMINI_API_KEY

这是从别家迁移过来时最容易卡住的一步——密钥没错、路径没错，但头名写错了。官方 SDK 会自动读取 GEMINI_API_KEY 环境变量并补上这个头，所以用 SDK 时通常感觉不到这层差别。

REST 接口的主机是 generativelanguage.googleapis.com，具体路径以官方文档当前的接口版本为准。

官方 SDK

官方提供统一的 Gen AI SDK：Python 装 google-genai，JavaScript 装 @google/genai，另有 Java 版本，也可以完全不用 SDK 直接发 HTTP 请求。

「统一」的含义是同一个库既能连开发者接口，也能连企业版平台——从个人试用过渡到企业环境时不用换库。

免费额度的代价

这是本页最需要认真读的一节。官方条款把免费与付费的区别写得很直接：

• 免费额度：提交的内容与模型返回的内容会被用于提供、改进和开发 Google 的产品；人工审阅者可能读取、标注和处理；官方明确建议不要提交敏感、机密或个人信息。
• 付费额度：声明不使用你的提示词与响应来改进产品。

结论很明确：用免费额度调提示词时必须用脱敏样例，真实客户数据要走付费额度并确认对应条款。这不是风险提示，是官方自己写在条款里的机制。

多模态输入

Gemini 系列以多模态见长，接口支持文本、图像与文件输入。对于图文混合的材料（截图、扫描件、带图表的文档），它通常比「先 OCR 再喂文本」的流程省事。

具体支持的文件类型、体积上限与保留时长以官方文档为准，这些限制调整较频繁，本页不写死。

OpenAI 兼容入口

官方另外提供了一个 OpenAI 兼容入口：把 Base URL 换成它、密钥换成 Google 签发的，OpenAI SDK 就能连上。

但官方自己给出了限制：该支持仍在 beta，且不是所有 OpenAI 参数都受支持——不支持的参数会被静默忽略，不报错也不生效。官方还建议：如果没有历史包袱，直接用原生接口更合适。

判断兼容到什么程度，逐项验证方法见 OpenAI 兼容接口怎么判断。

限流与计费

同样存在分层限流，免费与付费额度的配额不同，具体数值以官方限流文档为准。计费按用量，token 的输入与输出分别计价。

触发限流时的应对策略与别家一致：读响应信息、按指数退避重试，并区分「速率超限」与「额度耗尽」——后者重试多少次都不会成功。

适合什么场景

• 需要处理图文混合材料的应用；
• 希望先在网页里把提示词调稳、再接入代码的团队；
• 已经在使用 Google 账号体系、想用统一 SDK 覆盖开发者接口与企业版平台的项目。

接入前要确认什么

• 要处理的是不是真实数据——是的话不要用免费额度；
• 请求头用的是不是 x-goog-api-key；
• 如果走兼容入口，用到的参数是否都真的生效（静默忽略不会报错）；
• 可用地区与结算方式是否已经确认。

上手教程见 Gemini API 使用教程；与 OpenAI 官方接口的横向差异见 OpenAI API vs Gemini API。