curl 调试 Gemini API:参数、错误码与排错手册
首页 / 文章 / 技术教程 / curl 调试 Gemini API:参数、错误码与排错手册
curl 调试 Gemini API:完整错误 JSON、Bash/PowerShell 双版本命令、401/403/429 排错顺序。Base URL https://api.itzyk.top/v1。
作者:Itzyk API · 发布:2026-09-30 · 更新:2026-11-14
一、前言 调用 Gemini 原生接口时,SDK 报错常夹杂代理、依赖与语言环境噪音,真正卡点往往是 401 / 403 / 429 或 JSON 参数写错。排错时 curl 更快 :一眼看出是网络、鉴权、模型名还是 Body 问题。 本文基于面向开发者的 OpenAI 兼容 AI API 网关—— 智枢ZhiShu / Itzyk API(api.itzyk.top) ,整理:必备 Header、对话/流式示例、 完整错误 JSON 报文 、 Bash 与 Windows PowerShell 双版本命令 ,以及可复制的排错顺序。Base URL 统一为 https://api.itzyk.top/v1 。建议任何语言接入前,先用 curl 打通。 --- 二、准备 Key 在用户控制台「API 管理」创建;需有余额。下面命令都假设已 export。 鉴权格式固定 少写 Bearer 、多空格、复制换行,都会变成神秘 401。 --- 三、必备四个命令 3.1 健康与公开状态(可不带 Key) 用于判断「整站是否活着」,和业务 Key 无关。 3.2 列出当前 Key 可用模型 若这里就 401/403,先别写业务代码。 3.3 非流式对话 关注: choices 0 .message.content 与 usage 。可用 jq 美化 3.4 流式对话 -N 关闭缓冲,才能看到 SSE 逐行 data: 。结束行为 data: DONE 。 --- 四、常用请求参数 | 字段 | 类型 | 说明 | |------|------|------| | model | string | 如 gemini-3.6-flash ;Pro 用平台上架 code | | messages | array | system / user / assistant | | temperature | number | 0~2,常用 0.2~0.7 | | max tokens | number | 限制输出长度,控成本 | | stream | bool | true 开启 SSE | 最小可用 body 多轮时按时间顺序追加消息;别把「当前用户话」重复塞两次。system 适合放角色与输出格式约束,保持简短。 --- 五、图像与视频(简表) 文生图 文生视频(按秒计费,联调用短时长) 图像/视频权限需在 Key 上开通;失败一般不扣费或按规则回退,以控制台为准。 --- 六、错误码速查(含真实 JSON 报文) | HTTP | 常见含义 | 你该做什么 | |------|---------|-----------| | 401 | 缺 Key / Key 无效 / 过期 | 检查 Bearer、重建 Key | | 402 | 余额或额度不足 | 充值;查 Key 限额 | | 403 | IP 白名单或模型未授权 | 放开权限 | | 404 | 路径或模型不存在 | 核对 URL 与 model code | | 429 | 限流 | 降并发,看 Retry-After | | 502/503/504 | 上游失败 / 超时 | 稍后重试;查状态页 | 把响应体保存下来(先看状态行,再看 message / type / code ): 6.1 典型错误响应体(便于整段搜索) 401 Invalid API Key(常见复制丢 Bearer 、用了官方 Google Key、Key 已删): 402 余额不足: 403 模型未授权 / 权限不足: 429 限流: 字段名以实际响应为准;排查时把完整 JSON 贴进工单(打码 Key),比只说「调不通」有效得多。 --- 七、标准排错顺序(请按序) 1. 无 Key 探活 : /health 是否 200 2. 有 Key 列模型 : /v1/models 是否 200 3. 最短 chat :一条 user ping 4. 换网络 :手机热点 vs 公司网(排除代理剥 Header) 5. 核对模型名 :与控制台/价格页完全一致 6. 再开 stream :非流式通了再测流式 7. 再上 SDK :curl 通了,语言侧问题多半是 baseURL 写错 每步只改一个变量。很多人同时改 Key、模型、代理,最后不知道哪步修好的。 隐蔽坑 - Base URL 写成 https://api.itzyk.top 少了 /v1 ,或多写了 /v1/v1 - 把 Google 官方 Key 当成平台 sk- 用 - JSON 里中文没正确 UTF-8,或 shell 引号把 JSON 截断 - 公司 HTTPS 检测导致 Authorization 丢失 - Windows 直接粘贴 Linux 单引号 curl :CMD/PowerShell 对 '...' 与换行处理不同,常出现 JSON 解析错误 Windows PowerShell 等价命令(勿用 Bash 单引号照抄) 或用 curl.exe(Win10+ 自带)时, -d 建议读文件,避免引号地狱: macOS / Linux 继续用本文第三节的 Bash 单引号写法即可。 --- 八、可保存的联调脚本 进项目后 chmod +x smoke.sh && ./smoke.sh ,发版前跑一遍。 --- 九、小结 curl 是 Gemini / Itzyk接入的「显微镜」:先验证鉴权与模型,再谈 SDK 与产品。记住四个命令——models、chat、stream、(可选)images/video——再配上错误码表和按序排错,绝大多数联调问题都能在 10 分钟内定位。 Key 与控制台:Itzyk控制台 。把 smoke.sh 留给团队,比口头说「我这边是通的」可靠得多。 --- 十、用 httpie / jq 提升可读性 若已安装 jq req.json 便于版本管理,避免在 shell 里嵌套引号到崩溃。httpie 用户可 工具不重要,重要的是: 请求可重复、响应可截图可贴 issue 。 --- 十一、对比两次请求做回归 改模型或改网关配置后,用同一 req.json 打两次,diff 内容与 latency 适合回答「换 Flash 还是 Pro」「延迟差多少」这类产品问题,有数据比靠感觉强。 --- 十二、代理与公司网络 若公司强制 HTTP 代理 若只有手机热点能通、公司网 401,优先怀疑中间盒剥掉 Authorization。可临时用 看实际发出的头。部分「网络连通性优化 / 分流代理」配置也可能导致个别域名不走预期出口,表现为偶发超时——先固定出口再比延迟。 --- 十三、把 curl 嵌进 CI 用 开发 Key + 极短 prompt ,避免 CI 打爆账单。失败则阻断部署。 --- 十四、FAQ Q:流式在 curl 里乱码? 检查终端 UTF-8;加 -N ;不要把 SSE 当整包 JSON 解析。 Q:为什么 models 有,chat 却 403? Key 可能对部分模型未授权,或 IP 白名单拦截了 chat 路径所在出口。 Q:超时多少合适? 文本 30~60s;图像/视频更长。curl 用 --max-time 60 。 Q:如何提交工单最有效? 附:完整 curl(隐藏 Key)、HTTP 状态、响应体、大致时间点、Key 名称(非密钥本身)。 --- 十五、小结补充 把本文的 smoke 脚本、错误码表、按序排错,收进团队 Wiki。新同学第一天不用问「接口怎么测」,跑脚本即可。Itzyk控制台:Itzyk控制台 。curl 通了再写代码,是减少联调时间最便宜的方法。 --- 十六、给支持同学的话术模板 当研发不在时,支持同学可以用固定话术收集信息 1. 请提供 Key 名称(不要发完整密钥)与大致调用时间 2. 请贴出脱敏后的 curl(Authorization 打码) 3. 请告知 HTTP 状态码与响应体前几行 4. 是偶发还是必现?换网络是否恢复? 有了这四项,排障人可以对照本文错误码表快速定位,而不必在聊天工具里来回猜。把话术和 smoke 脚本一起放进支持手册,响应速度会明显提升。 若是 402,直接引导充值或检查子账号额度;若是 429,引导降低并发或错峰;若是 401,引导重建 Key 并检查是否误用官方 Google Key。 --- 十七、与监控系统联动 把关键 curl 变成黑盒探测:每分钟请求一次极短 chat,失败则告警。探测使用专用低额度 Key,prompt 固定为单个词,费用可忽略。告警级别区分 - 连续失败:紧急(可能全站故障) - 偶发 502:观察 - 402:通知财务与管理员 探测结果进仪表盘后,「用户说不能用」可以先看探测是否绿,减少盲目排查。 --- 十八、结束语 curl 看起来土,却是跨语言、跨团队的公共语言。把参数表、错误码、排错顺序和 CI 冒烟固定下来,Itzyk Gemini 的联调成本会大幅下降。先让命令行变绿,再让 SDK 变绿——这个顺序请长期坚持。 --- 十九、建立团队「最小可复现」文化 很多线上争议来自「我这边可以 / 你那边不行」。强制要求:报告问题必须附最小 curl。能一条命令复现,就不要贴几百行业务日志。研发复现后,把根因归类进本文错误码与隐蔽坑,形成活文档。 对偶发问题,记录:时间、地区、运营商、是否 VPN、HTTP 状态、耗时。偶发 502 与必现 401 的处理路径完全不同。把一周内的 curl 失败样例做归类统计,比凭记忆开
本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。