Gemini API CLI：给AI Agent的多模态工具，但小心账单

Google 最近为编码 Agent 提供了一个新工具，只需一行命令就能生成图像、视频和配音——但它的名字很容易让人误解。它叫 Gemini API CLI，并非之前那个面向个人账户的 Gemini CLI。两者有本质区别：旧版 Gemini CLI 是一个编码 Agent，Google 已对个人账户关闭；而 Gemini API CLI 根本不是 Agent，而是一个命令行工具。

工具与 Agent 的界限

CLI（命令行界面）是一个通过输入一行指令来运行的程序。Gemini API CLI 的定位就是如此：它不替你规划任务，也不主动调用模型，只是把多模态生成能力封装成一条命令。真正使用它的是你的编码 Agent——Agent 负责决策，CLI 负责执行。

这种分工解决了此前的一个痛点。在没有这个工具之前，Agent 每生成一张图片都要写一个一次性脚本，然后收到一大段文本输出，这些文本会挤占 Agent 的上下文记忆空间，导致后续任务效率下降。现在，Agent 只需输入一行命令，图片就直接落到文件夹里，Agent 拿到的只是一个文件路径。

Agent 拿到的只是一个文件路径，而不是一堆文本。

这个变化看似微小，但对 Agent 的工作流影响很大：上下文更干净，后续推理更稳定，也减少了因输出过长而触发的截断问题。

CLI 与 Agent 的本质区别在于控制流向。CLI 是确定性的执行器：给定参数便返回结果，不做任务分解，也不维护跨步骤状态。Agent 则是带有循环的决策系统，它观察环境、规划步骤、调用工具、再根据结果调整。把多模态生成封装成 CLI，相当于给 Agent 提供了一件「原子工具」——Agent 的推理循环留在自己手里，生成动作交给外部进程。这也符合 Agent 工具设计的常见原则：工具应尽量单一职责、输出尽量结构化，而由 Agent 承担编排。

上下文窗口是 LLM 在一次推理中能看到的全部 Token 总量，包含系统指令、对话历史、工具输出等。它既是容量上限，也是成本与延迟的来源。当工具返回大段文本（如 base64 编码图像或冗长日志）时，这些内容会长期占据上下文，挤压后续推理的可用空间，并可能触发截断，导致 Agent 丢失早期关键信息。让工具只回传文件路径，本质是把「数据」移出上下文、只保留「引用」，是减少上下文污染的标准做法。

多模态能力：图像、视频、音乐与字幕

Gemini API CLI 覆盖的不只是图像。同一套工具还能生成音乐和视频，并能将任意录音转成字幕。对于需要快速产出多媒体素材的开发者来说，这意味着不必在多个 API 和脚本之间切换，一条命令就能完成从生成到落盘的全过程。

这种“一条命令出结果”的设计，让 Agent 的多模态任务从“写脚本-解析输出-提取文件”的繁琐流程，简化为“发命令-收路径”的两步操作。开发者可以把更多精力放在 Agent 的逻辑设计上，而不是文件处理的胶水代码上。

免费的工具，不免费的模型

这里有一个关键提醒：工具本身免费，但背后的模型不是。据视频来源说明，文本和语音有免费额度，图像和视频则没有。视频生成的成本约为每秒 10 美分。

这个定价结构带来一个现实问题：你的 Agent 现在可以自主花钱了。当 Agent 判断需要生成一段视频时，它可能连续调用多次，费用会迅速累积。每秒 10 美分的价格意味着一段几十秒的视频就可能达到数美元。对于个人开发者或小团队，这需要在 Agent 的决策逻辑中加入成本控制——比如设置预算上限、限制视频生成的调用频率，或者在非必要场景下优先使用免费额度的文本和语音能力。

按量计费（Pay-as-you-go）与免费额度是云 API 常见的两种定价方式。免费额度通常以请求数、Token 数或时长计量，超出后转为按量计费；多模态模型由于计算密集，往往不设免费额度或额度极低。这意味着「工具免费」并不等于「使用免费」，真正的成本发生在每次模型调用上。对于被 Agent 自动触发的调用，费用会随调用次数线性叠加，且没有人工确认环节。

该不该给 Agent 一个预算？

Gemini API CLI 的价值在于它把多模态能力变成了 Agent 可调用的标准动作，同时保持了上下文的整洁。但它也把“成本意识”这个新课题摆在了开发者面前。工具免费降低了尝试门槛，模型收费则要求开发者对 Agent 的行为有更精细的约束。

一个务实的做法是：在 Agent 的指令中明确预算边界，把视频生成这类高成本操作设为需要确认的动作，或者只在明确需要时才启用。文本和语音的免费额度可以承担大部分日常任务，图像和视频则留给真正需要的场景。

是否给 Agent 独立的预算，取决于你对自动化程度的接受度。工具已经就位，剩下的就是设计一套让 Agent 既能干活又不至于失控的规则。

**人工确认（Human-in-the-loop）**指在高风险或高成本动作执行前插入人工审批环节。在 Agent 系统中，常见实现是把工具划分为只读、可逆写、高成本三类，仅对后两类要求确认。另一种控制手段是设置调用配额与熔断机制：为单次任务设定调用次数上限或金额上限，超出即中止并回报。这些约束最好写在 Agent 的系统指令与工具层的硬性限制中双管齐下——仅靠提示词约束并不可靠，工具层拒绝执行才是最后一道防线。