Gemini API CLI：让编码 Agent 调用 Gemini 处理图片、视频、PDF 和深度研究

Gemini API CLI（gemini-api）是 Google 为 Gemini API 提供的开源命令行客户端，专为 Claude Code、Codex、Cursor 和 Antigravity 等编码 Agent 构建。安装一个 Go 二进制，设置 GEMINI_API_KEY，Agent 就能生成图片、视频、语音和音乐，分析 PDF 和录音，把音频转写成 SRT，并在后台启动 Deep Research。

下文涵盖安装、认证、Agent 会运行的命令、与 Gemini CLI 的区别，以及如何配合 Apifox CLI。所有参数来自 2026 年 10 月 30 日发布的 0.4.5 版 gemini-api --help。

什么是 Gemini API CLI？

Gemini API CLI 是 Google Interactions API 的无状态单二进制客户端。每个命令是一次 HTTP 调用：输入提示词，输出文件路径、逐字稿、分析结果或 interaction ID。它是现有 Agent 在任务需要 Gemini 时调用的工具。

Google 的官方文档页称其为“随 Interactions API 演进的开源 beta 版本”。代码位于 google-gemini/gemini-api-cli，Apache 2.0 许可，可运行于 macOS、Linux 和 Windows。

0.4.5 版 gemini-api --help 的内容：

Gemini API CLI 与 Gemini CLI 的区别

Gemini CLI（@google/gemini-cli）是交互式编码 Agent，一个你可以对话的 Claude Code 替代品。Gemini API CLI（gemini-api）没有 Agent 循环，是另一个 Agent 调用的工具。

如果你在 Claude Code 或 Codex 中工作，并希望把 Gemini 的媒体和研究模型带入工作流，请用 gemini-api。这与 OpenAI CLI 的模式相同，只是指向 Google。

如何安装

从 README 选择四种方式之一。

macOS 和 Linux：

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

Go：

go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

预编译二进制： 从 GitHub Releases 下载对应平台压缩包，用 checksums.txt 校验，把 gemini-api 放到 PATH。我们使用 Darwin_arm64 压缩包，shasum -a 256 -c checksums.txt --ignore-missing 输出 OK。

Google 警告小版本之间可能出现破坏性变更，因此在 CI 中锁定版本。文档展示了在 bash 前放置 GEMINI_VERSION=<release-tag> 的安装脚本。

确认安装：

gemini-api version
# gemini-api 0.4.5

认证

在 Google AI Studio 创建密钥（获取步骤见《如何在 2026 年免费使用 Gemini》），然后导出：

export GEMINI_API_KEY="YOUR_API_KEY"

在自有工作站也可以存储：

gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami

configure 把密钥保存到操作系统钥匙串（macOS Keychain、Linux Secret Service 或 Windows Credential Manager）。添加全局 --no-keyring，则保存在 ~/.config/gemini-api/config.yaml。whoami 显示当前凭据及来源。

未设置密钥时，gemini-api --help 会打印写给 Agent 的提示：API 密钥“必须由用户在 Google AI Studio 中手动创建。停止并请用户创建”。Agent 会来问你，而不是自行配置。

用 --dry-run 预览调用

--dry-run 校验参数并打印请求（凭据脱敏），不发起网络调用，也不读取钥匙串。它在设置密钥前就能工作，我们正是这样检查本文示例。

后台 Deep Research 任务的 dry run：

每个命令都 POST 到 https://generativelanguage.googleapis.com/v1beta/interactions。添加 -o json 可在 stdout 获得每次请求一个 JSON 对象，Agent 可在消耗 token 前解析。

Agent 会运行的命令

生成和编辑图片

gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg
gemini-api image "Add a winter scarf" -i ./assets/mascot.jpg --out ./assets/mascot-winter.jpg

媒体命令写入文件并只打印路径，Agent 可用 $(...) 捕获并继续。image 还接受 --aspect-ratio 和 --image-size（512、1K、2K 或 4K）。默认模型是 Nano Banana 2.1；具体能力见《Nano Banana 2.1 API 使用指南》。

生成视频、语音和音乐

gemini-api video "A slow camera move through a sunlit workshop" --resolution 1080p --out ./assets/
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api music "Warm ambient music for a product walkthrough" --out ./assets/

video 会替你轮询；--async 立即返回操作句柄，--resume <id> 稍后继续轮询。--resolution 默认 720p。

分析 PDF、图片和 YouTube URL

gemini-api analyze -i product-brief.pdf "What should we build first, and why?" > plan.md
gemini-api analyze -i before.png -i after.png "Summarize the visual design changes"

-i/--input 可重复，接受本地路径、files/<id> URI 或 YouTube URL。内联输入上限约 14 MB。更大文件请上传一次并复用 URI：

FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze -i "$FILE_URI" "List the key action items with timestamps"

上传文件 48 小时后删除。

转写音频和视频

gemini-api transcribe -i interview.mp4 --format srt --out interview.srt

--format 接受 md（默认）、text、json 或 srt。--no-speakers 或 --no-timestamps 可去掉说话人或时间戳。

后台运行 Deep Research

ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$ID" --stream=false --output-format json

--background 立即返回 interaction ID，而不是保持流打开。Agent 保存 ID，去做别的事，再用 agent status 检查。agent cancel 停止运行。0.4.5 还列出 deep-research-max-preview-04-2026 和 antigravity-preview-05-2026。

对 Agent 更安全的标志

来自 gemini-api --help-global：

• --agent-mode（或 GEMINI_CLI_AGENT_MODE=1）：stderr 输出结构化 JSON 错误，stdout 输出紧凑 TOON。
• -o, --output-format：pretty、json、yaml、table 或 toon。
• -q, --jq：内联过滤，例如 --jq '.id'。
• --no-interactive：禁用提示和 TUI 表单，无头 Agent 需要。
• --usage：以机器可读 KDL 输出完整命令树。
• --schema（按命令）：--body payload 的 JSON Schema。

退出码让 Agent 无需解析文本：0 正常，1 运行时或 API 失败，2 用法或校验错误，3 认证失败。一个坑：流式命令（generate、agent run）需要先加 --stream=false，这样 -o json 或 --jq 才会给出单个可解析结果；否则会输出多条流式事件。

把 CLI 交给编码 Agent

Google 的 README 提供可粘贴到 AGENTS.md、CLAUDE.md 或 .cursorrules 的内容。精简版：

You have access to gemini-api through the shell.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run.
3. For JSON output or --jq on streaming commands, pass --stream=false --output-format json.
4. Capture returned file paths and interaction IDs to continue multi-step tasks.

确保 GEMINI_API_KEY 能传入 Agent 子进程。然后照常提示：“构建落地页，用 Gemini 做吉祥物图片和 20 秒配音，并针对竞品启动 Deep Research。”Agent 会选择命令。

它做不到实时语音或视频。没有 WebSocket 支持，Live API 仍需 GenAI SDK。

用 Apifox CLI 测试你构建的 API

gemini-api 提供 Gemini 模型，但对你的 API 一无所知：无论是你的应用围绕 Gemini 包装的 /summarize 或 /thumbnail 端点、它的环境，还是证明发布没有破坏功能的断言。那是 Apifox CLI 的工作，同一个 Agent 可同时运行两者。

先配置：

npm install -g apifox-cli@latest
apifox login --with-token <YOUR_TOKEN>
npx -y skills add https://apifox.com   # 按提示选择你的 Agent

给 Agent 一段提示：

Use gemini-api to dry-run an analyze call on ./docs/sample-invoice.pdf, then run it for real.
Import ./openapi.yaml into Apifox project <id>, create a test case for POST /v1/invoices/extract
that uploads the same PDF and asserts a 200 and a non-empty "total" field, run it against the
staging environment, and summarize any failures.

Agent 先用 gemini-api 检查 Gemini 回答，再读取 Apifox schema、验证 payload、创建并运行用例：

apifox import --project <id> --format openapi --file ./openapi.yaml
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox test-case create --project <id> --file case.json
apifox run --test-case <caseId> --project <id> -e <envId> -r cli,json

apifox test-case create --help 指出一个陷阱：用例需要有效 categoryId，先用 apifox test-case category --project <id> 列出。把 -r cli,json 换成 -r junit，同一行命令可在 CI 运行。如果 Agent 是 Claude Code，建议先阅读站内的《Apifox CLI：常驻终端的 API 客户端》。Apifox 免费版不限制成员数量和协作人数。

常见问题

Gemini API CLI 免费吗？ CLI 本身免费，Apache 2.0 开源。每次调用都按 Gemini API 定价计入你的 API 密钥账单。免费层覆盖什么，见《如何在 2026 年免费使用 Gemini》。

gemini-api 和 Gemini CLI 一样吗？ 不一样。Gemini CLI 是交互式编码 Agent；gemini-api 是无状态工具，供其他 Agent、脚本和 CI 调用。

没有 API 密钥可以测试命令吗？ 可以。--dry-run 校验命令并打印确切请求，不发起网络调用，也不读取钥匙串。本文示例都在 0.4.5 上这样检查。

如何处理大于 14 MB 的文件？ 运行 gemini-api files upload <file> --wait，保留返回的 files/<id>，在 analyze、transcribe、generate、image、video 或 agent run 的 -i 中传入。上传 48 小时后过期。

应该锁定版本吗？ 应该，尤其在 CI 中。Google 表示 beta 期间小版本之间可能出现破坏性变更。