Google 发布了命令行工具 Gemini API CLI（命令是 gemini-api），让 Codex、Claude Code 等现有 Agent 能从终端调用 Google 的多模态模型和托管 Agent。它目前处于预览阶段，接口仍可能变动。

它把几类工作放进了同一个工具：

• 跨平台安装：提供跨 macOS、Linux 与 Windows 的单二进制文件，无需安装 Node.js、Python 或配置复杂的语言环境。
• 生成与理解素材：一个命令行工具覆盖文本推理、图像生成与编辑、多发言人语音合成、背景音乐生成、视频创作，以及长文档/音视频理解与字幕转录。
• 文件直接存进项目：生成的图片、视频、音频写入本地文件，终端默认只返回路径，方便 Agent 接着使用。
• 先查用法、再检查请求：Agent 可以离线查看命令和参数，并用 --dry-run 检查请求的写法。
• 委托后台研究任务：支持以非阻塞方式启动 Gemini 后台托管 Agent（如 Deep Research），立即返回交互 ID（Interaction ID），方便宿主 Agent 随时轮询状态与获取结构化结果。
• 自己保存任务接续信息：CLI 不保存本地对话历史，宿主 Agent 需要保留上下文，或通过服务端交互 ID 接续。

你继续用原来的 Agent，Gemini 提供它调用的能力

让 Codex 或 Claude Code 帮你写一个落地页时，仍由它决定页面结构、判断需要哪些素材、运行命令，再把生成的文件接回页面。这个负责推进整项任务的 Agent，就叫“宿主 Agent”。把模型能力接进业务后端代码，通常使用 SDK，也就是相应编程语言的调用库；让 Agent 从终端临时生成素材，则可以直接使用 CLI，也就是命令行工具。

图里是一个共同底座、两个并列入口：

• Gemini API 与托管 Agent（底座）：统一的多模态模型与服务端点，涵盖推理模型（Gemini 3.8 Flash）、图像生成（Gemini Nano Banana 2.1）、视频生成（Gemini Omni 1.1 Flash）、音乐合成（Lyria 3.5）、语音合成（Gemini 3.8 Flash TTS）与托管研究服务（Deep Research）。
• Google Gen AI SDKs（代码入口）：面向生产后端与微服务代码，提供 Python、TypeScript、Go 与 Java 的类型化客户端库。
• Gemini API CLI（命令行入口）：即本次发布的 gemini-api 单二进制文件，面向终端操作与 Coding Agent 的 Shell 循环调用，负责直接与 API 通信并将媒体文件落盘。

使用时认准完整名称 Gemini API CLI 和命令 gemini-api，不要与 Gemini CLI 混淆。

在典型的自主编码场景中，各方的分工如下：

• 宿主 Agent（如 Codex、Claude Code、Google Antigravity、Cursor、OpenClaw 等）：负责规划构建任务（例如编写网页），决定何时需要生成什么素材，并在终端中运行命令、接回生成的文件。
• Gemini API CLI（gemini-api）：负责在 Shell 中接收参数并调用 API，将生成的媒体文件直接写入磁盘，并向标准输出返回文件路径或交互 ID。
• Gemini 模型与平台服务：负责处理具体请求，执行图像绘制、音频合成、跨模态理解与后台深度研究。

少写接入脚本，让生成的文件直接交给下一步

在构建落地页等实际任务中，如果让 Coding Agent 直接通过通用网络请求调用多模态 API，生成的图片或音频数据若是直接以 Base64 等编码原样打印到终端标准输出，就会被宿主 Agent 当作终端输出读入会话，白白占用宝贵的上下文空间。

虽然开发者也可以让 Agent 自己写脚本请求接口并将数据写入本地文件，但这需要额外编写解析响应、提取数据和保存文件的代码，还可能遇到依赖或格式处理的问题。gemini-api 把这个过程封装成了标准行为：在生成图片、音频或视频时，CLI 会自动把文件写到磁盘指定位置，终端标准输出默认只打印生成文件的本地路径。这样既省去了编写临时接入与解析保存代码的工作，也避免了媒体编码直接涌入终端占据 Agent 的上下文。

gemini-api image "Isometric icon of a distributed database" --out ./assets/

在具体流程中，宿主 Agent 为落地页生成头图时，只需运行一条命令，CLI 将图像写入磁盘并向标准输出返回路径，宿主 Agent 再按项目的资源目录和页面引用方式，把这个文件接入 <img> 标签，继续搭建页面。对于结构化数据，也可以通过 --output-format json 配合内置的 --jq 筛选提取所需字段。

装好并配置 gemini-api 后，可以把下面的完整任务发给正在使用的 Codex、Claude Code 或 Antigravity。中英文任选一种，发到 Agent 的对话框里：

# 英文提示词原文 / English prompt
Build a landing page for this app. Use Gemini to create a mascot image and a welcome voiceover, and launch a managed research agent to investigate competing products. Incorporate the assets and findings into the page.

# 中文提示词译文（与英文任选其一发送给宿主 Agent）
为这个应用构建一个落地页。使用 Gemini 创建一个吉祥物图像和一段欢迎配音，并启动一个托管研究 Agent 调研竞品。将这些素材与调研结论整合进页面中。

你交代目标，宿主 Agent 决定调用哪些命令。素材生成后接入页面，竞品研究完成后再把结论整合进去。

从生成图片，到配音、转字幕和后台研究

实际调用 API 前，先完成安装与凭证配置；离线查用法和预检不需要发起 API 调用。除 Windows 安装命令外，下面的命令示例使用 Bash 语法，适用于 macOS、Linux 或 Windows 上的 Bash 环境（如 WSL）。请把示例路径换成实际文件。

1. 图像生成与二次编辑

gemini-api image 默认使用 gemini-nano-banana-2.1 模型。通过 --out 参数可以指定输出文件或保存目录；若指向目录，CLI 会自动根据 API 返回的 MIME 类型追加文件后缀（如 .jpg）。

# 英文示例
gemini-api image "Isometric icon of a distributed database" --out ./assets/database-icon.jpg

# 中文译文（与英文任选其一执行）
gemini-api image "分布式数据库的等距视角图标" --out ./assets/database-icon.jpg

执行后，标准输出仅打印文件绝对或相对路径（例如 ./assets/database-icon.jpg）。

若要在已有图像基础上进行二次编辑，官方 README 给出了机器人吉祥物生成与修改的完整两步示例（通过 -i 或 --input 传入原图路径；任选英文或中文整套执行）：

# 英文示例（两步完整执行）：
# 第一步：生成初始机器人图像并捕获输出路径
MASCOT_PATH=$(gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg)

# 第二步：使用 -i 传入原图进行编辑
gemini-api image "Add a winter scarf and snowy background" -i "$MASCOT_PATH" --out ./assets/mascot-winter.jpg

# 中文示例（两步完整执行，与英文任选其一）：
# 第一步：生成初始机器人图像并捕获输出路径
MASCOT_PATH=$(gemini-api image "友好可爱的机器人吉祥物，柔和摄影棚光照" --out ./assets/mascot.jpg)

# 第二步：使用 -i 传入原图进行编辑
gemini-api image "添加一条冬季围巾与雪景背景" -i "$MASCOT_PATH" --out ./assets/mascot-winter.jpg

2. 视频生成

gemini-api video 默认使用 gemini-omni-1.1-flash 模型，通过对话式视频生成能力将文本转化为动态画面。

# 英文示例
gemini-api video "A slow camera move through a sunlit workshop" --out ./assets/workshop.mp4

# 中文译文（与英文任选其一执行）
gemini-api video "镜头缓慢穿行于阳光照亮的车间" --out ./assets/workshop.mp4

3. 多角色语音合成与背景音乐

针对需要配音或背景音效的场景，gemini-api tts 提供了多发言人对话合成能力（底层使用 Gemini 3.8 Flash TTS），而 gemini-api music 则基于 Lyria 3.5 纯音乐生成模型。

# 多发言人对话语音合成（英文示例）
gemini-api tts "Alice: Deployment succeeded! Bob: Let's ship it." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./assets/dialogue.wav

# 多发言人对话语音合成（中文译文，与英文任选其一执行）
gemini-api tts "Alice: 部署成功！Bob: 我们发布吧。" \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./assets/dialogue.wav

命令中的 Alice 与 Bob 是台词角色，Kore 与 Puck 是分配的声音，台词角色名与映射左侧保持一致；整段内容合成后保存为一份对话音频。

# 背景音乐生成（英文示例）
gemini-api music "Lo-fi ambient background track for a focus app" --out ./assets/focus-bg.mp3

# 背景音乐生成（中文译文，与英文任选其一执行）
gemini-api music "适合专注应用的低保真氛围背景音乐" --out ./assets/focus-bg.mp3

4. 多模态文档分析与语音转录

gemini-api analyze 与 gemini-api transcribe 用于对已有素材进行理解，默认底层模型均为 gemini-3.8-flash。除了本地 PDF、图像、音视频和文本文件外，gemini-api analyze 也可以直接传入 YouTube 链接进行分析。

# 针对本地 PDF 进行分析（英文示例）
gemini-api analyze -i architecture.pdf "Summarize the key bottlenecks"

# 针对本地 PDF 进行分析（中文译文，与英文任选其一执行）
gemini-api analyze -i architecture.pdf "总结主要瓶颈"

这类分析默认把文字返回终端，宿主 Agent 可以继续使用；若要留成文件，也可像 README 示例那样用 > plan.md 保存。

宿主 Agent 修改页面后，还可以把修改前后的两张截图一起交给 Gemini，总结视觉设计变化。--input 可重复传入多个文件；把 before.png 和 after.png 换成自己的截图路径：

# 对比两张截图的视觉设计变化（英文示例）
gemini-api analyze --input before.png --input after.png "Summarize the visual design changes"

# 对比两张截图的视觉设计变化（中文译文，与英文任选其一执行）
gemini-api analyze --input before.png --input after.png "总结视觉设计变化"

# 将会议或采访录音转录为带时间戳的 SRT 字幕
gemini-api transcribe -i earnings_call.mp3 --format srt --out earnings_call.srt

官方在转录示例中展示了如下生成的 earnings_call.srt 字幕样例：

1
00:00:03,000 --> 00:00:07,000
Speaker 1: Welcome to the third quarter earnings call.

2
00:00:16,000 --> 00:00:20,000
Speaker 1: Revenue grew 20% year-over-year.

每条字幕依次是序号、出现与消失的时间、字幕文本。两句话的意思分别是“欢迎参加第三季度财报电话会议”和“营收同比增长 20%”；对照时间码，就能知道这句话在录音中的位置。

README 建议较大的媒体文件（原始文件约 14 MB 以上，Base64 编码后约 20 MB）先走 Files API：通过 files upload --wait 预先将大文件上传至托管存储（Files API 保留 48 小时），随后复用返回的 URI 即可：

# 上传大文件并提取暂存 URI，再进行分析（英文示例）
FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze --input "$FILE_URI" "List the key action items with timestamps"

# 上传大文件并提取暂存 URI，再进行分析（中文译文，与英文任选其一执行）
FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze --input "$FILE_URI" "列出带时间戳的关键待办事项"

5. 后台托管Agent（Deep Research）的长任务接续

对于耗时较长、包含多步骤网络检索与交叉验证的复杂任务，CLI 提供了非阻塞的后台执行模式：

# 启动后台 Deep Research 任务（英文示例）
INTERACTION_ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

echo "Started interaction: $INTERACTION_ID"

# 启动后台 Deep Research 任务（中文译文，与英文任选其一执行）
INTERACTION_ID=$(gemini-api agent run "研究电池回收途径并注明信源" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

echo "Started interaction: $INTERACTION_ID"

仅使用这里的启动与查询命令，并不会自动获得完成通知；宿主 Agent 需要自行保存返回的交互 ID（INTERACTION_ID）。在任务执行期间，宿主 Agent 可以继续推进其他工作，并通过 agent status 主动查询状态或进度；查询能看到任务状态，完成后再读取研究结果：

# 查询任务当前状态；任务完成后获取结构化 JSON 结果
gemini-api agent status "$INTERACTION_ID" --stream=false --output-format json

Agent 不会用时，可以先让工具解释自己的用法

目前在 Google Antigravity 中，开发者已经可以通过工作区 Shell 调用 gemini-api，官方表示原生集成仍在计划中。官方还用 Antigravity 2.0 调用 gemini-api video 制作了本次发布的宣传视频片段；下图展示工作区里的命令和生成文件预览。

在项目里告诉 Agent 何时使用它

如果想让 Claude Code、Codex、Cursor、Antigravity 或自定义 Agent 顺畅调用 gemini-api，可以在项目根目录的配置说明（如 AGENTS.md、CLAUDE.md 或 .cursorrules）中加入以下指令块（提供完整英文原文与中文译文，任选一种语言放入配置文件）：

# 英文配置原文 / English instructions
You have access to gemini-api through the shell.
Use it to call Gemini models, generate or edit media, analyze files, or launch managed agents.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run (or --dry-run --output-format json).
3. For discrete JSON output or --jq filtering on streaming/background commands (generate, agent run, agent status), pass --stream=false --output-format json.
4. Capture returned file paths (from media commands) and interaction IDs (from agent/model runs) to continue multi-step tasks.

# 中文配置译文（与英文任选其一放入配置文件）
你可以通过 Shell 访问 gemini-api。
使用它来调用 Gemini 模型、生成或编辑媒体、分析文件或启动托管 Agent。
1. 查看 --help 或 --usage 选择命令；构造 --body JSON 载荷时查看 --schema。
2. 使用 --dry-run（或 --dry-run --output-format json）预览 API 调用。
3. 对于流式或后台命令（generate、agent run、agent status），传入 --stream=false --output-format json 以获取离散 JSON 输出或进行 --jq 过滤。
4. 捕获媒体命令返回的文件路径，以及模型/Agent 运行返回的交互 ID（interaction ID），以便接续多步任务。

查参数、预检和取结果，各有对应命令

1. 自描述接口与模型查询： gemini-api --help 用来查命令和参数，--usage 则提供机器可读的命令树。比如 Agent 想要生成图片但不记得当前模型名称时，可以先运行裸命令 gemini-api models 查看内置的离线模型目录，或运行 gemini-api models list --all 查询当前 API 密钥可用的全部实时模型，再用 -m 显式指定具体型号。对于接受请求体的命令（如 image、agent run 等），Agent 可以运行 gemini-api <command> --schema 导出内置的请求结构规范，以便准确构造载荷。

2. 离线校验（Dry-run）： 在正式触发网络请求前，可以在命令后附加 --dry-run。CLI 会在本地完成参数校验并输出脱敏后的 HTTP 请求预览，期间不发起网络请求，也不读取操作系统钥匙串。需要注意的是，--dry-run 仅验证本地参数拼写与请求形态是否合法，并不证明远端 API 密钥有效、当前账号具备该模型调用权限、存在可用配额，也无法验证生成结果的质量。

3. 输出契约与 Agent 模式： 开启 --agent-mode（或设置环境变量 GEMINI_CLI_AGENT_MODE=1）后，CLI 会在发生错误时向 stderr 输出标准的 JSON 错误信封，并将 stdout 的默认输出收敛为紧凑格式；同时支持明确的退出码（0 为成功，1 为运行时/API 错误，2 为参数校验失败，3 为鉴权或授权失败）。

4. 从简单 Flag 到自定义载荷（--schema 到 --body）： 短参数能够满足日常高频需求，但如果需要微调底层生成参数，可以使用 --body 注入完整 JSON 载荷。例如，生成指定比例（16:9）与高分辨率（2K）的素材（下面的中英文请求体任选一种）：

   查看英文请求体 hero-image.json（README 完整原文）

   cat > hero-image.json <<'JSON'
   {
     "model": "gemini-nano-banana-2.1",
     "input": "A friendly robot mascot in a sunlit workshop, composed on the right with uncluttered space on the left for a landing page headline. No text or watermark.",
     "response_format": {
       "type": "image",
       "aspect_ratio": "16:9",
       "image_size": "2K"
     },
     "store": false,
     "stream": false
   }
   JSON
   

   查看中文请求体 hero-image.json（与英文任选其一执行）

   cat > hero-image.json <<'JSON'
   {
     "model": "gemini-nano-banana-2.1",
     "input": "阳光照亮的车间里有一个友好的机器人吉祥物，构图靠右，左侧留出供落地页大标题使用的干净空间。无文字或水印。",
     "response_format": {
       "type": "image",
       "aspect_ratio": "16:9",
       "image_size": "2K"
     },
     "store": false,
     "stream": false
   }
   JSON
   

   # 离线验证载荷合法性
   gemini-api image --body @hero-image.json --out ./assets/hero.jpg --dry-run --output-format json
   
   # 正式执行
   gemini-api image --body @hero-image.json --out ./assets/hero.jpg --output-format json
   

   这里的 --out 决定文件存在哪里，response_format 决定要生成什么规格的图片；--output-format json 会让终端返回包含文件路径等字段的产物元数据，区别于默认的单行路径。

5. 无状态设计与跨轮次会话串联： CLI 本地不存储任何会话历史，但这并不代表服务端无状态。服务端的交互记录由 API 自身管理生命周期，宿主 Agent 可以在多轮对话中保存上一轮返回的交互 ID，并通过 --body 中的 previous_interaction_id 显式接续对话：

   # 英文示例
   # 第 1 轮：执行推理并捕获服务端返回的 interaction ID
   TURN1_ID=$(gemini-api generate "Propose 3 database indexing strategies for a time-series log table." \
     --stream=false --jq '.id')
   
   # 第 2 轮：引用 previous_interaction_id 接续对话
   gemini-api agent run "Compare strategy #2 and #3 for write-heavy workloads." \
     --body "{\"previous_interaction_id\": \"$TURN1_ID\"}" \
     --stream=false
   

   # 中文译文（与英文任选其一执行）
   # 第 1 轮：执行推理并捕获服务端返回的 interaction ID
   TURN1_ID=$(gemini-api generate "针对时序日志表提出 3 种数据库索引策略。" \
     --stream=false --jq '.id')
   
   # 第 2 轮：引用 previous_interaction_id 接续对话
   gemini-api agent run "对比策略 2 与策略 3 在写入密集型工作负载下的优劣。" \
     --body "{\"previous_interaction_id\": \"$TURN1_ID\"}" \
     --stream=false
   

怎样装好并开始用

1. 安装方式

官方提供了一键安装脚本与源码编译途径：

• macOS 与 Linux (Bash)：

  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 开发环境的用户，编译当前 main 分支需 Go 1.26.10 或更高版本）：

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

2. 凭证配置与离线验证

安装完成后，必须确保 gemini-api 二进制文件已放入系统的 PATH 环境变量中，并且宿主 Agent 启动的子进程能够访问到同一环境与配置。你可以在 Google AI Studio 获取 API key，并将其提供给 CLI。

CLI 支持多种凭证保存方式（凭证可能保存到操作系统钥匙串中，也可能写入 ~/.config/gemini-api/config.yaml 配置文件，视系统环境与所选参数而定）：

# 方式 A：设置环境变量（适合 CI/CD 或 Agent 子进程环境）
export GEMINI_API_KEY="your-api-key"

# 方式 B：持久化保存（写入操作系统钥匙串或本地配置文件）
gemini-api configure --api-key "your-api-key"

# 方式 C：启动终端交互式表单引导
gemini-api configure

配置完成后，推荐使用离线命令查看当前配置并验证环境：

# 查看当前生效的配置与凭证来源（不验证凭证在远端是否有效）
gemini-api whoami

# 离线验证请求构造（英文示例，不发起网络请求）
gemini-api generate "Hello from my agent" --dry-run

# 离线验证请求构造（中文译文，与英文任选其一执行）
gemini-api generate "来自我的 Agent 的问候" --dry-run

3. 配额与费用说明

官方文档未提供统一的 CLI 订阅套餐。实际调用的权限、配额与计费完全取决于用户所提供的 GEMINI_API_KEY 所属账号体系，以及每次调用具体指定的模型（如 Gemini 3.8 Flash、Nano Banana 2.1、Lyria 3.5 或 Deep Research 等）的官方定价与配额策略。开发者现有的第三方 Agent 订阅（如 Claude Pro、Cursor、Codex 等）不能视为包含此 API 额度，实际调用按 Gemini API 的规则处理。

当前 gemini-api 处于实验性预览阶段（v0.4.x），接口与参数可能发生破坏性变更。在自动化流水线或生产环境中集成时，建议固定具体的发布版本号；--dry-run 仅能进行本地参数和请求形态检查，版本升级后仍需通过实际的关键 API 调用来进行最终验证。