Gemini Web 2 API 使用手册

部署前准备

先确认分发包、配置文件和访问方式，避免一开始就把问题带到接口层。

Binary First

你需要准备什么可执行文件、同目录的 config.json、可用网络环境，以及你自定义的 api_key。

建议先做什么优先确认 /api/telemetry 返回 JSON，再开始接 SDK 或 curl。

推荐目录结构把可执行文件和 config.json 放在同一目录，部署、迁移和备份都更简单。

不要先想着编译源码当前帮助页服务的是分发出去的成品程序，除非你本身就是维护者。

四步快速开始

目标是让第一次接入的用户在几分钟内跑通请求链路。

4 Steps

1编辑配置打开 config.json，先设置 api_key。只有需要代理或 Cookie 时再补其他字段。

2启动程序Windows 可双击程序；命令行可运行 .\<程序名>.exe，Linux/macOS 可执行 ./<程序名>。

3检查服务访问 /api/telemetry，确认状态、请求数和 uptime 返回正常。

4发送请求向 /v1/chat/completions 发 OpenAI 兼容请求，并带上 Bearer Key。

config.json 示例

{
  "api_key": "change-me",
  "proxy": "",
  "cookies": "",
  "log_level": "info",
  "note": ["geminiweb2api running"]
}

配置项说明

只展示真正影响交付的字段，避免帮助页继续堆技术噪声。

KISS

api_key对外暴露给客户端的 Bearer Key，请求头使用 Authorization: Bearer <api_key>。

proxy只有在网络环境需要代理时才填写，例如 http://127.0.0.1:7890。能不配就不配。

cookies用于 Gemini Web Cookie 场景，能提高 token 获取与刷新稳定性，不是所有部署都需要。

log_level排错时建议临时切到 debug，问题恢复后再切回 info。

关于保留字段像 tokens 这类当前没有实际行为的字段，不建议在主流程里强调，避免用户误以为必须配置。

接口总览

把常用入口讲清楚，比堆大段说明更适合用户手册阅读。

OpenAI Compatible

GET /api/telemetry查看服务是否在线，以及请求数、RPM 和 token 统计。

GET /v1/models用于模型列表探测，适合 SDK 初始化或健康检查。

POST /v1/chat/completions主要对话入口，兼容 OpenAI Chat Completions 格式。

GET / 与 GET /help分别是监控大屏与用户手册，适合部署者和一线使用者查看。

请求示例

所有示例会自动带入当前页面的 Base URL，复制后改 key 即可。

chat completions

curl -s "{{BASE}}/v1/chat/completions" \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: demo-session" \
  -d '{"model":"gemini-3-flash","stream":false,"messages":[{"role":"user","content":"你好"}]}'

streaming sse

curl -N "{{BASE}}/v1/chat/completions" \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: demo-session" \
  -d '{"model":"gemini-3-flash","stream":true,"messages":[{"role":"user","content":"用三句话介绍你自己"}]}'

openai node sdk

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "change-me",
  baseURL: "{{BASE}}",
});

const resp = await client.chat.completions.create({
  model: "gemini-3-flash",
  messages: [{ role: "user", content: "你好" }],
});

console.log(resp.choices[0]?.message?.content);

openai python sdk

from openai import OpenAI

client = OpenAI(
  api_key="change-me",
  base_url="{{BASE}}",
)

resp = client.chat.completions.create(
  model="gemini-3-flash",
  messages=[{"role": "user", "content": "你好"}],
)

print(resp.choices[0].message.content)

会话与流式说明

把多轮对话保持逻辑讲清楚，用户才能稳定复现问题与结果。

Session

会话保持多轮对话时固定使用同一个 X-Session-ID，或者在请求体里传 conversation_id。

SSE 结束标记当 stream=true 时，服务会以 SSE 方式返回分块内容，并最终以 data: [DONE] 收尾。

代理对流式更敏感如果流式返回中断，先检查代理与网络质量，再看是否需要降低并发。

故障排查

把高频问题前置，减少“像程序坏了，实际上是环境没通”的误判。

Troubleshooting

返回 HTML、验证码或被拦截通常是 Gemini 侧风控。优先更换 IP 或代理，必要时补充 cookies。

请求超时或连接被拒绝先检查 proxy 是否可用；没配代理时，再检查系统级网络环境。

多轮对话上下文丢失确认同一用户会话使用固定 X-Session-ID，不要每次随机生成。

需要更多排错信息把 log_level 临时改成 debug，复现问题后再切回常规级别。

安全提醒api_key 和 cookies 都属于敏感信息，不要提交到 Git，也不要直接暴露到公共网络。

常见问题

最后再补充用户最容易问到的几个判断点。

FAQ

必须配置所有字段吗？不需要。通常只要 api_key 就可以开始，其他配置按需启用即可。

为什么强调二进制分发？因为交付对象拿到的大多是成品程序。手册应该服务部署和调用，而不是让普通用户去理解源码结构。

服务启动后先看哪里？先看监控大屏和 /api/telemetry。如果服务自身没在线，SDK 示例再正确也跑不通。

怎么验证调用成功？一是响应体正常返回，二是监控大屏里的总请求数、成功数和 token 统计出现变化。