PuppyIP 资源中心
AI API 教程 5 分钟 发布于 2026-11-18

Gemini API CLI 怎么用?脚本和 CI 的安装、预检与费用

脚本或 CI 要调用 Gemini 时,可以用 Gemini API CLI 的 gemini-api 命令。它通过 Interactions API 发起调用。先固定命令行版本,再离线检查请求。真实调用使用 API 项目的权限、配额和计费。

Gemini API CLI gemini-api Interactions API CI

服务对象与地域限制

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。