首调：AI Studio Key、SDK 安装与 interactions.create

你将得到什么

• 一个可用的 GEMINI_API_KEY（来自 Google AI Studio）
• 本机已安装 google-genai（Python）或能跑通 REST curl
• 一次成功的 client.interactions.create(...)，能打印 output_text，并看到 status=completed

官方把 Interactions API 定为新项目默认接口（约 2026-06 起）；本课只走这条路径，不讲旧版 generateContent。

开始前准备

1. 浏览器能打开 aistudio.google.com/apikey（需 Google 账号）。
2. 本机二选一：
   • 路径 A：Python 3.9+ 与 pip
   • 路径 B：任意终端 + curl（不装 SDK 也能验收）
3. 可选：Node.js 18+（文末附官方 JS 片段，主路径以 Python / curl 为准）。

不要把 API Key 写进仓库或截图外传；只用环境变量。

步骤 1：在 AI Studio 创建 API Key

1. 打开 Create a Gemini API Key。
2. 新用户通常会自动有一个项目与 Key；否则点 Create API key，按对话框绑定/新建项目。
3. 复制 Key，在本机终端写入环境变量（官方写法）：

export GEMINI_API_KEY="YOUR_API_KEY"

对照结果：

# 只确认变量非空，不要把 Key 打印进日志或聊天
test -n "$GEMINI_API_KEY" && echo "GEMINI_API_KEY is set (len=${#GEMINI_API_KEY})"

应看到 GEMINI_API_KEY is set (len=...)，且 len 明显大于 0。若为空，重新 export 或检查 shell 是否新开了未继承环境的窗口。

免费档即可完成本课；速率有限。若以后要更高配额，官方文档说明需在 AI Studio 走 Cloud Billing 升级付费档（本课不要求）。

想先在网页里试提示词：打开 Google AI Studio，用 Chat 调 system instructions，满意后再点 Get code 导出——流程见 AI Studio quickstart。本课直接走 API。

步骤 2（路径 A）：安装 Python SDK 并首调

官方安装命令：

pip install -U google-genai

对照结果：安装结束无报错；可再确认：

python -c "import google.genai as g; print('google-genai OK')"

应打印 google-genai OK。

新建文件 first_interaction.py（与 Getting started 一致；Client() 会读环境变量 GEMINI_API_KEY）：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works in a few words",
)
print(interaction.output_text)
print("id=", interaction.id)
print("status=", interaction.status)

运行：

python first_interaction.py

对照结果（字段以你本机 SDK 对象为准，语义与官方 REST 示例一致）：

常见失败：

• API key not set / 401：当前 shell 没有 GEMINI_API_KEY。
• 模型名 404：确认拼写为官方示例 gemini-3.8-flash（文档会随发布更新；以 get-started 页为准）。
• 429：免费档速率限制，稍后再试。

步骤 3（路径 B）：用 curl 打 REST（不装 SDK）

官方 REST 端点与请求体：

curl -sS -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": "Explain how AI works in a few words"
  }' | tee /tmp/gemini-interaction-1.json

对照结果（官方文档给出的结构要点）：

• HTTP 200
• JSON 含 "object": "interaction"、"model": "gemini-3.8-flash"
• "status": "completed"
• "steps" 里至少有一个 "type": "model_output"，其 content[].text 为回答正文
• 常有 "usage"（如 total_input_tokens / total_output_tokens）

快速抽正文（需本机有 jq）：

jq -r '.status, .id, (.steps[] | select(.type=="model_output") | .content[]? | select(.type=="text") | .text)' \
  /tmp/gemini-interaction-1.json

应先看到 completed、一行 interaction id，再看到模型文本。

步骤 4（可选）：流式输出

官方 Python 流式写法（便于 UI 打字机效果）：

from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works",
    stream=True,
)
for event in stream:
    print(event)

对照结果：终端连续打出多个事件对象（官方 SSE 语义含 interaction.created、step.delta、interaction.completed 等）。REST 流式需在 URL 加 ?alt=sse 且 body 设 "stream": true，见官方 Streaming 小节。

步骤 5（可选）：Node.js 首调

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: "Explain how AI works in a few words",
});
console.log(interaction.output_text);

对照结果：与 Python 相同，打印一小段解释文本。

本课检查清单

• GEMINI_API_KEY 已 export，且未提交到 git
• pip install -U google-genai 或 curl REST 任一路径跑通
• 打印出非空 output_text，并记下 interaction.id（下一课多轮要用）

下一课：用 previous_interaction_id 做服务端托管多轮，并挂上 google_search 工具。