服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Google 在 2026 年 10 月 27 日发布 Gemini API CLI 测试版。gemini-api 面向自动化,交互式 Gemini CLI 有独立的使用流程。
- macOS、Linux 与 Windows 可用官方版本归档。CI 应记录选用的版本与运行平台。
- --dry-run 可离线校验请求。需要单个 JSON 响应时,文本生成可用 --stream=false -o json。
- 命令输出结构和实际 API 费用需要分别核对。媒体命令写文件,模型和工具的使用按实际项目及功能确认。
先确定脚本要调用哪个工具
Gemini API CLI 的可执行文件叫 gemini-api。它面向已有 shell 的自动化任务,通过 Interactions API 生成文本或媒体、分析文件,以及调用 Gemini 托管代理。这里的无状态指命令不依赖隐藏的本地会话。要接续对话,应在工作流里明确保存并传入上一次的 interaction ID。
如果目的是在终端里与编码代理交互,Google 文档另列 @google/gemini-cli。给应用编写长期服务时,也可以评估官方 SDK。已经写好的 shell 脚本若只需调用一次模型,gemini-api 适合直接接入。
固定版本,再配置项目密钥
从官方文档所链的 GitHub Releases 选择与系统、架构匹配的 macOS、Linux 或 Windows 预编译归档,将二进制放入 PATH。CI 和容器应固定归档版本,在构建记录里保留版本和平台。测试版升级时先在独立任务里核对所用参数和输出,再替换流水线版本。
通过既有 CI 密钥存储把 GEMINI_API_KEY 注入实际执行命令的进程。API 项目负责权限、配额和费用。检查当前凭据来源可参考官方 whoami 命令,诊断时保留来源信息即可,避免在日志里输出密钥。
先做离线预检,再验证调用
例如,准备让流水线处理一段不含敏感信息的测试文本。先用 gemini-api generate "Confirm CLI setup in one sentence." --dry-run 预览。文档说明预检在本地校验参数并展示脱敏后的请求。复杂请求可先用 gemini-api generate --schema 核对 --body 的结构。
预检只能确认本地参数和请求形状。首次联网验证用获准的项目与小输入,核对实际模型、权限和返回。脚本需要读单个 JSON 时,用 --stream=false -o json。先检查返回格式,再接入下游解析,避免把流式片段当作完整的 JSON 文档读入。
处理文件输出、退出码和后续调用
媒体命令通常将结果写到文件,标准输出可提供路径。带 -o json 时应按文档读取元数据,再从工作目录取文件。把产物路径和文本结果分别保存,有助于明确缺的是模型结果、元数据还是本地文件。
退出码 2 指参数或输入验证问题,3 指身份验证或授权问题。退出码 1 包括网络、限额或运行时错误,应先读脱敏错误信息判断原因。使用 --agent-mode 可让错误以 JSON 写入标准错误。涉及后台交互时,把返回的 ID 保留下来,以便后续查询。
按实际项目和模型核费用
接入前核对 Gemini Developer API 定价页中目标模型与使用功能对应的层级。有些模型或功能不提供免费额度,已开通付费的项目也要确认所选模型、工具和使用量。个人 Gemini 订阅或 CLI 安装成功本身无法确认该 API 项目可用的额度。
先用可控的小输入比较预期与实际用量,再扩大调用规模。遇到费用或权限问题时,记录项目、模型与时间,用原始错误类型核对。本文的设置示例用于说明流程,项目单价和可用范围以实际 API 资料为准。
资料来源
常见问题
设置了 --dry-run 可以证明项目有模型权限吗?
离线预检只检查请求的本地构造。用授权项目发起小规模真实调用,才能核对模型权限、配额和网络。
文本调用不传上一轮 ID 会自动继续聊天吗?
命令默认不保留隐含会话。需要延续交互时,通过 --previous-interaction-id 明确传入上一轮 ID。