跳转到主要内容
本指南直接调用 Gemini 的 generateContent 协议。先确认渠道和模型支持原生 Gemini 请求;本例使用部署方签发的网关令牌,放入 x-goog-api-key 请求头。

地址与请求结构

项目从模型路径分配渠道;请求头中的令牌用于网关认证,上游认证由渠道适配器负责。项目也接受查询参数 key,但本例只使用请求头,避免密钥出现在 URL 中。

运行准备

需要 Node.js 22.18+ 或 24;使用内置 fetch,无需 Google SDK。预先设置 API_KEY,再设置根地址与实际模型:
保存为 native-gemini.mts 后运行 node native-gemini.mts;文档目录中运行 node examples/native-gemini.mts。本例限制模型 ID 为字母、数字、点、下划线或连字符,拒绝 models/ 前缀、路径和动作后缀;这是示例的地址校验范围,不是网关全部模型命名规则。

TypeScript

完整示例:

读取结果

本例要求恰好一个候选、finishReason: STOP、role: model 和非空可见文本。promptFeedback.blockReason、MAX_TOKENS、SAFETY、错误对象及工具/媒体块均使示例失败。它跳过标记为 thought: true 的文本;只有思考内容而没有可见答案也会失败。成功打印拼接后的回答,失败不输出部分答案、不跟随重定向、不自动重试。 工具调用使用 tools[].functionDeclarations、functionCall 和 functionResponse,不能直接复用 Chat 的工具消息。多轮时保留整个 model 内容(包括渠道返回的 thoughtSignature 和工具标识)再加入新 user 内容;展示时隐藏 thought 不意味着重放时可以丢弃签名。本例只展示单轮文本,不实现原生工具闭环。

流式路径与支持边界

原生 SSE 使用 POST /v1beta/models/{model}:streamGenerateContent?alt=sse。stream: true 加在 generateContent 请求体里不能代替切换动作。每个 SSE data 是 Gemini 响应对象,不是 Chat delta 或 Responses 的具名事件。按候选索引处理 parts 和最终 finishReason;HTTP 成功或 EOF 都不能单独证明正常完成。网络数据块可能截断一个 UTF-8 字符或 SSE 事件。 本文可执行示例覆盖 generateContent 文本响应;原生 SSE 与工具闭环提供完整 Python 流式实现。图片/音频扩展与真实渠道仍需另行实现和联调。不要把 Chat / Responses 流式工具示例的事件解析器用于 Gemini。 项目未实现 /v1beta/...:countTokens,当前返回 404,不能依赖供应商 SDK 的计数方法。模型路由、可选字段及不同渠道的转换能力应按部署验证。 Gemini generateContent 参考 · 错误处理 协议依据:Google generateContent / streamGenerateContent。项目端点和认证行为以本仓库路由及适配器为准。 Read in English