Gemini API 调用指南：Interactions 与 GenerateContent

先区分官方推荐与本站兼容范围

Google 已在 2026 年 6 月把 Interactions API 设为 GA，并推荐所有新项目使用；原 generateContent 仍受支持，但已归为 Legacy。本站是否支持某个端点取决于网关适配，不能因为 Google 已发布 /v1beta/interactions 就假设本站也已开放。当前公开的 Gemini 原生兼容路径确定是 GenerateContent。

通过本站调用 GenerateContent

本站推荐使用 Authorization: Bearer；为兼容 Gemini 原生客户端，/v1beta/models/... 路径也接受本站密钥形式的 x-goog-api-key。模型名位于 URL 中并应来自模型广场。contents[].parts 可组合文本和模型支持的多模态输入；不要发送官方单模型页未声明的内容类型。

Copycurl "$BASE_URL/v1beta/models/MODEL_NAME:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"只回复：连接成功"}]}]}'

直连 Google 的 Interactions 形态

直连 Google 使用 x-goog-api-key。Interactions 调用 POST /v1beta/interactions，把 model 和 input 放入 JSON；响应包含 id、status、usage 与类型化 steps[]。SDK 的 output_text 适合读取简单最终文本，遇到思考、工具、图片或音频交错时必须按 type 遍历 steps。

多轮可用 previous_interaction_id，但工具、system instruction 和 generation config 不会自动继承，应在后续请求中重发。store=false 适合不希望服务端保存交互的场景，但不能再依赖已存储交互续接。

两套响应和流式事件不能混用

GenerateContent 返回 candidates、finishReason、promptFeedback 和安全信息；Interactions 使用 interaction.created、step.start/delta/stop 与 interaction.completed 等类型化 SSE 事件。函数调用在新协议中也是独立 step，不再是简单替换 function response part。HTTP 200 后仍可能出现流内错误，客户端要容忍未知事件并等待明确完成事件。

错误与重试

401 检查认证，403 检查权限，404 检查模型或资源，429 可能是速率或配额。先读错误 status 和 message 再处理 5xx：过载或临时服务故障可有限退避，但 GenerateContent 的输入或上下文过长也可能表现为 500 或 504，此时必须缩短请求而不是重试。参数、安全拦截和配额问题同样需要修正请求或账户。保存请求 ID、错误 code、status 与最终 step，参见 API 报错排查。

迁移前必须核验的边界

Interactions 尚未覆盖 GenerateContent 的全部能力，例如部分视频 metadata、Batch、显式缓存和自定义安全设置。迁移前逐项核验目标型号、/v1 或 /v1beta、文件限制、工具、结构化输出、存储策略与数据政策，并分别保留两套契约测试；不要只改 URL。