项目介绍

gemini-api 是一个无状态的 Gemini API 命令行客户端，面向已经有 shell 访问权限的编码 Agent 和助手工具。它不需要单独做 SDK 集成，而是把文本与多模态生成、媒体创作、文件分析和托管 Agent 运行变成普通命令；宿主 Agent 负责规划，CLI 负责调用，再把返回的文件路径或 interaction ID 交回 Agent 继续流程。

命令按任务组织：generate 做文本生成，image/tts/music/video 做媒体生成，analyze 针对 PDF、图片、音视频、CSV 和 YouTube URL 提问，transcribe 输出 Markdown、纯文本、JSON 或 SRT 字幕，agent 用于运行和管理 Gemini 托管 Agent；另有文件、模型、凭据、webhook、触发器、沙箱环境等管理命令 命令总览。它以单个 Go 二进制分发，支持 macOS、Linux 和 Windows，目前处于 beta 阶段 状态说明。

快速使用

准备一个 Google AI Studio 的 Gemini API key 和可用的 shell。安装方式包括平台安装脚本、go install，或从 GitHub Releases 下载预编译包；README 记录了完整安装入口 安装说明。

1. 让 key 可用于当前环境：

export GEMINI_API_KEY="YOUR_API_KEY"

如需持久保存，可运行 gemini-api configure --api-key "YOUR_API_KEY"（写入系统钥匙串或配置文件），或 gemini-api configure --interactive 打开交互表单 配置步骤。

2. 先做不发网络请求的本地校验，再正式调用：

gemini-api generate "Hello from my agent" --dry-run
gemini-api generate "Hello from my agent"

README 建议首次调用前先用 --dry-run 检查 快速开始。

3. 在宿主 Agent 的 AGENTS.md、CLAUDE.md、.cursorrules 或工具配置中加入说明，让它知道应查看 --help/--usage、用 --dry-run 预览、用 --output-format json 获取 JSON，并保留返回的文件路径和 interaction ID。一条典型的媒体命令会写入文件并打印路径：

gemini-api image "A friendly robot mascot for a developer tool" --out ./assets/

Agent 接口

命令、参数、请求 schema 和环境变量/配置键都可以从二进制自身获取：--usage 以 KDL 输出完整命令树，--schema 打印接受请求体的命令所附的 JSON Schema，--dry-run 会在不联网、隐去凭据的情况下预览解析后的 HTTP 请求 Agent 发现接口。--agent-mode 会在 stderr 输出结构化 JSON 错误，并默认使用紧凑的 TOON 输出；--output-format json 可显式选择 JSON。退出码区分成功（0）、运行时失败（1）、参数或校验错误（2）和认证失败（3）。

短参数覆盖不到的场景可以用 --body 传入完整的 Interactions API 请求体；README 演示了查看 image schema、编写 JSON 请求体，再配合 --out 与 --dry-run 执行的过程 自定义请求体。

使用约束

• 项目处于 beta，版本之间可能出现破坏性变更；README 建议在 CI 和自动化工作流中固定到具体 release 版本 状态说明。
• 必须提供 API key，调用费用按你的 Gemini API 账户结算；key 需放在 shell 环境里，或通过 configure/auth 存储。
• CLI 不保存本地对话状态。多轮延续依赖服务端 interaction 和 previous_interaction_id；上传文件有自己的保留期限（README 称 Files API 为 48 小时）。
• 较大的媒体文件应先用 files upload --wait 上传一次，再通过 URI 复用，而不是直接内联。
• 项目采用 Apache-2.0 许可证，且当前不接受 pull request 许可与贡献。

HotRepo 点评

仓库在 HotRepo 的记录中首次出现于 2026-11-07，当天位列 Go 语言日榜第 3，新增 16 Star，累计 462 Star、73 Fork。这只是单日快照，能说明当天的关注度，不足以判断趋势。更值得注意的是它的接口设计：--usage、--schema、--dry-run、--agent-mode 和明确的退出码都围绕「让已有 shell Agent 直接调用 Gemini、不必另写胶水代码」这一目标；beta 状态和必须持有有效 API key 是当前采用它的实际限制。