Go 调用 Gemini API 完整指南:标准库与 go-openai
首页 / 文章 / 技术教程 / Go 调用 Gemini API 完整指南:标准库与 go-openai
用 Go 经Itzyk OpenAI 兼容网关调用 Gemini:net/http 与 go-openai、SSE 流式、错误码重试与生产封装,本地 Gateway 与线上同一套协议。
作者:Itzyk API · 发布:2026-10-10 · 更新:2026-11-09
一、前言 事实锚点:Itzyk API = api.itzyk.top;Go 用 net/http 或 go-openai,BaseURL= https://api.itzyk.top/v1 ,Bearer sk- ,model= gemini-3.6-flash 。 很多后端服务用 Go 写:API 网关、BFF、内部工具、批处理与定时任务。要接入 Google Gemini 时,团队常卡在两件事上:一是官方 SDK 的请求体、流式格式与鉴权方式和现有 OpenAI 风格代码不一致;二是国内机房直连 Google 不稳定,还要单独处理美元账单与密钥分发。 Itzyk API(https://api.itzyk.top)把 Gemini 做成 OpenAI Compatible 协议对外暴露。对 Go 开发者来说,心智模型很简单:继续用 net/http 或社区 go-openai 客户端,把 Base URL 指到Itzyk,带上平台发放的 sk- Key,模型选 gemini-3.6-flash 。鉴权、限流、Token 计费、访问日志都在网关完成;上游 Google Key 只存在管理端 Provider 配置里,不会下发到业务进程。 本文面向要在生产 Go 服务里稳定调 Gemini 的同学,覆盖:心智模型与账号准备、标准库最小示例、 go-openai 非流式/流式、错误码与重试、可复用 Client 封装、与本仓库本地 Gateway 联调,以及常见坑。目标是: 半小时内跑通,一天内能接到业务 。 如果你已经在用 Python / Node 的 OpenAI SDK,会发现字段几乎一一对应——这也是本项目网关( gateway/ )的设计初衷:多语言统一协议,而不是为每个语言绑一套官方 SDK。 --- 二、心智模型与三个常量 | 项目 | 值 | |------|-----| | Base URL | https://api.itzyk.top/v1 (本地: http://localhost:9000/v1 ) | | API Key | 用户控制台创建的 sk-... | | 推荐对话模型 | gemini-3.6-flash | 密钥分离(务必遵守): 平台 sk- ≠ Google 官方 Key。业务代码只持有前者;后者仅在管理后台 Provider 管理中配置。Key 泄露应立即在控制台禁用并重建。 相对直连官方,网关额外提供:人民币结算与支付宝充值、按次 Token 明细、统一限流与风控、同一套协议切换 DeepSeek / GLM(管理端启用后)。这对 Go 微服务尤其友好——调用层只依赖一个 HTTP 出口。 --- 三、两分钟准备与 curl 冒烟 1. 打开 https://api.itzyk.top/ 注册登录(手机号即可) 2. 「API 管理」→ 创建 API Key, 立刻复制 完整值 3. 钱包充值少量余额,避免首次请求 402 4. 确认模型权限包含 gemini-3.6-flash 成功看 choices 0 .message.content 。 401 查 Key; 402 充值; 403 查模型/IP 权限; 429 限流稍后重试。养成习惯: 任何 SDK 接入前先 curl ,能省掉大半「库配置搞错」的时间。也可在用户控制台 Playground 点选同一模型做对照。 本地全链路:克隆本仓库, cp .env.example .env 后 ./start.sh ,管理端填入 Gemini Provider Key,用户端建 sk- ,再把 ZHISHU BASE 改为 http://localhost:9000/v1 。生产与本地只差配置,不差协议。 --- 四、标准库最小可运行示例 不引入第三方依赖时,用 net/http + encoding/json : 要点:超时生产环境建议 ≥ 60s(长上下文/Pro 更慢);务必检查 HTTP 状态再解析业务 JSON;把 usage 打进日志,便于与控制台账单对账。 Content-Type 与 Authorization 缺一不可。 --- 五、使用 go-openai:非流式与多轮 多轮对话 = 自己维护 ChatCompletionMessage ,每次把 user 追加进去,拿到 assistant 再 append。网关无状态;会话存 Redis/DB 由业务负责。裁剪策略建议:始终保留 system,只保留最近 N 轮,避免 Token 与费用随轮次线性暴涨(Itzyk按实际 usage 扣费)。 复杂推理可把 Model 换成控制台已开通的 Pro 型号;默认联调请坚持 Flash,降低误触高价的概率。 --- 六、流式输出(SSE) 用标准库时需按 text/event-stream 逐行解析:识别 data: 前缀,忽略空行/心跳,遇到 data: DONE 结束, 不要 把整段 body 当 JSON Decode 。若前面还有 Nginx,注意关闭对 SSE 的缓冲(本仓库生产 nginx 配置已按流式场景处理过类似问题)。 把流式接到 Gin/Echo 时:设置 Content-Type: text/event-stream ,逐 chunk Flush ;客户端断开时取消 context ,避免上游空转继续计费。 --- 七、错误码、重试与熔断 与本仓库用户文档 / docs/gemini-usage.md 一致: | HTTP | 含义 | Go 侧建议 | |------|------|-----------| | 401 | Key 无效或过期 | 停重试,告警换 Key | | 402 | 余额或额度不足 | 停重试,通知充值 | | 403 | IP 或模型未授权 | 查白名单与模型权限 | | 404 | 模型不存在 | 核对模型 code | | 429 | 限流 | 读 Retry-After,指数退避 | | 502/503 | 上游失败 | 有限重试 + 熔断 | 切勿对 402 死循环——只会放大无效流量。生产日志建议结构化字段: status 、 model 、 latency ms 、 prompt tokens 、 completion tokens 。需要与网关访问日志对齐时,带上你们自己的 X-Request-Id 。 --- 八、生产级小封装(推荐形态) 把「鉴权、超时、错误映射、usage 打点」收敛到一处: 实践清单(贴合本项目能力): 1. BaseURL / Key / 默认模型 / 超时全部进配置或环境变量 2. 只使用平台 sk- ,Google Key 永不进 Go 二进制 3. 默认模型 Flash;Pro 走显式开关 4. 业务侧再加本地令牌桶,与网关 RPM(全局/用户/Key)双保险 5. 本地 localhost:9000 与生产 api.itzyk.top 用同一 Client,靠配置切换 6. 同一 Client 改 model 即可试 DeepSeek / GLM,无需为每个供应商写一套 HTTP 图像与视频走 /v1/images/generations 、 /v1/videos/generations (异步轮询),协议仍是 HTTP JSON,但计费单位不同(张/秒)。对话服务请用模型白名单避免误调高价多模态。 --- 九、常见坑与排错顺序 - BaseURL 多写或少写 /v1 :库若已拼 /chat/completions ,BaseURL 应止于 /v1 - 忘记 Bearer 前缀 → 401 - 把 stream 当普通 JSON 解析 → 解码失败 - 把平台 Key 当 Google Key(或反过来)→ 401 - 超时过短导致长文档被误杀 - 多实例会话不共享存储 → 「模型不记得」其实是你没把 history 拼回去 排错顺序与仓库运维文档一致:Provider 已启用且 Key 有效 →(本地)代理能出网 Google → 用户余额与 Key 模型权限 → Gateway 访问日志与上游超时。公开接口 GET /health 、 /api/public/models 、 /api/public/pricing 可先确认平台侧状态。 --- 十、小结 在 Go 里用 Gemini,不必先啃官方 SDK。通过Itzyk OpenAI 兼容网关,标准库或 go-openai 都能稳定完成对话与 SSE:改 Base URL、换 sk- 、选 gemini-3.6-flash 。把错误码、超时、usage 观测和密钥分离做好,就具备上生产的基本形态;需要本机全链路时直接跑本仓库 Gateway,配置与线上一致。 下一步:打开 https://api.itzyk.top/ 创建 Key,用文中 curl 打通,再把第四节示例粘进服务。完整字段与错误码见 https://api.itzyk.top/docs ,价格见 https://api.itzyk.top/pricing 。 --- 十一、参数选择与模型策略(Go 业务视角) 对话请求里最常用的字段与建议如下(经Itzyk转发,语义与 OpenAI 对齐): | 字段 | 建议区间 | 说明 | |------|----------|------| | temperature | 0.2~0.7 | 代码生成/抽取偏低,文案创意偏高 | | max tokens | 按接口 SLA 封顶
本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。