跳到正文

Gemini API 入门：一分钟内完成第一次调用

获取 Gemini API 密钥、安装 SDK，用 Interactions API 完成第一次调用——这是 Google 自 2026 年 6 月起为所有新项目推荐的接口。

当前有效最后核验

适用平台

  • Gemini API（Python、JavaScript、Java、REST）

官方文档怎么说

新项目从 Interactions API 开始

Google 的 Gemini API 现在有两套接口：自 2026 年 6 月起成为默认选项的 Interactions API——所有新模型、新的多模态能力、新工具和新的智能体功能都会先在这里上线；以及最初的 generateContent，它依然可用，但官方文档已经把它标注为旧版。如果你是从零开始，官方的建议非常明确——用 Interactions API。

这个区分对照着旧教程或者 AI 生成的代码样例来学习的人尤其重要：外面流传的很多示例代码仍然是面向 generateContent 写的。它还能继续跑，但你是在 Google 已经明确降低优先级的路径上搭建东西。

获取 API 密钥

每一次请求都需要密钥。你第一次登录 Google AI Studio 时,它就会自动帮你创建好项目和密钥——第一次试用不需要自己动手配置任何东西：

  1. 打开 Google AI Studio 的 API 密钥页面，直接复制 AI Studio 已经为你创建好的密钥。

  2. 如果你需要另一个密钥，或者想为不同的项目单独配置一个，点击 Create API key，按对话框把新密钥和项目配对。

  3. 把密钥设置为环境变量，这样代码里就不用硬编码它：

    export GEMINI_API_KEY="YOUR_API_KEY"

做到这一步，免费层级的调用就够用了。这一步完全不需要信用卡。

安装 SDK 并完成第一次调用

按你使用的语言选一个。

Python：

pip install -U google-genai

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="用几句话解释一下 AI 是怎么工作的"
)
print(interaction.output_text)

JavaScript：

npm install @google/genai

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "用几句话解释一下 AI 是怎么工作的",
});
console.log(interaction.output_text);

如果你想完全跳过 SDK，也可以直接用 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.8-flash",
    "input": "用几句话解释一下 AI 是怎么工作的"
  }'

这次 REST 调用值得亲自跑一遍：返回的是完整的 Interaction 资源——包含 id、status、usage，以及一个 steps 数组，里面可能先有一个 thought 步骤，再有 model_output 步骤。SDK 给你的 interaction.output_text 只是通向最终文本的一个捷径，但实际在网络上传回来的是这个完整资源，在开始依赖这个捷径之前，值得先看一眼原始结构。

流式获取响应

只要是交互式场景，就不要等整段答案返回——用流式：

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="解释一下 AI 是怎么工作的",
    stream=True
)
for event in stream:
    print(event)

每个 step.delta 事件都携带响应中的一段文本，这样你就可以在内容生成的同时逐段渲染，而不是阻塞等待整个调用完成。

让你的编码智能体也读到同样的文档

如果你在用 AI 编码助手（Claude Code、Codex 或类似工具）开发，Google 发布了一个技能包，能让助手直接、实时地访问 Interactions API 文档，而不是依赖训练数据里记住的内容：

npx skills add google-gemini/gemini-skills --skill gemini-api-dev

接下来去哪里

跑通一次纯文本调用之后，自然的下一步是：想在写代码之前先可视化试一试提示词，看 Google AI Studio；想了解定价和速率限制，看 Gemini API 概览；需要让 Gemini 真正去做点什么而不只是回答问题时，看函数调用与工具。

实际操作

  1. 打开 Google AI Studio，从 API 密钥页面直接复制自动创建好的密钥，或点击 "Create API key" 新建一对密钥和项目。
  2. 把密钥设为环境变量：`export GEMINI_API_KEY="YOUR_API_KEY"`。
  3. 按语言安装 SDK——Python 用 google-genai，JavaScript 用 @google/genai，或者直接用 REST。
  4. 用 gemini-3.8-flash 这样的 model 和一段 input 字符串调用 client.interactions.create。
  5. 从 interaction.output_text 读取答案，或者查看完整的执行步骤历史了解更多细节。
  6. 想要边生成边显示响应，就改传 stream=True（Python）或 stream true（JavaScript）。
  7. 如果免费层的速率限制不够用，设置 Cloud Billing 并预付最低 5 美元，升级到付费层级。

Windows 步骤

不适用Gemini API 本身在 Windows 上没有特殊设置，只需正常安装 Python/Node/Java；操作系统相关的工具链细节在 Gemini CLI 教程中说明。

手机步骤

不适用入门指南讲的是在开发机上使用 SDK 和 REST，没有说明手机端的用法。

使用案例

  • 在把 SDK 接入正式应用之前，先验证 API 密钥和模型名称本身是否可用。
  • 在脚本里先跑通一次纯文本生成调用，再决定要不要加流式输出或工具。
  • 在设置 Cloud Billing 之前，先看看免费层级的速率限制是否够用。

常见错误

  • 出于习惯或照抄旧教程继续用 generateContent 写新代码。Interactions API 才是新项目的当前默认选项，generateContent 虽然还能用，但官方文档已经把它标为旧版。
  • 以为有了 API 密钥速率限制就会提高。提高限制需要实际设置 Cloud Billing 并预付额度，光有密钥不够。
  • REST 调用时忘了带 x-goog-api-key 请求头——只带普通的 Authorization 头无法通过身份验证。
  • 只看 SDK 提供的 output_text 便捷属性，从不看完整的步骤历史，等到启用工具后突然出现 thinking 或工具调用步骤时感到意外。

常见问题

必须用 Interactions API 吗，还能继续用 generateContent 吗？
generateContent 仍然完全受支持，现有的接入不会失效。但官方文档已经把它标记为旧版路径——Google 自己的建议是新项目应该使用 Interactions API。
Gemini API 一开始是免费的吗？
是的。Google AI Studio 会自动创建项目和 API 密钥，免费层级不需要设置 Cloud Billing 就能调用。付费层级的更高速率限制和功能才需要单独设置结算。
client.interactions.create 到底返回了什么？
一个 Interaction 资源——包含 id、status、用量统计，以及按时间顺序排列的执行步骤列表（思考过程、工具调用和最终的模型输出）。SDK 里的 output_text 属性只是指向该资源最终文本内容的一个便捷入口。
怎样流式获取响应而不是等待完整结果？
在 interactions.create 中传入 Python 的 stream=True 或 JavaScript 的 stream true。这样得到的不是一次性的响应，而是一系列事件，每个 step.delta 事件都携带一段文本，可以边生成边显示。
我在用 AI 编码助手，它能自己学会 Interactions API 吗？
Google 专门发布了一个技能包用于这个场景：运行 `npx skills add google-gemini/gemini-skills --skill gemini-api-dev`，就能让编码助手直接访问当前的 Interactions API 文档和最佳实践，而不是依赖训练数据里过时的记忆。

官方来源

这些是本教程对照核验的官方页面。需要厂商的原始措辞时请直接查阅。

来源状态