Gemini API CLI
Gemini API CLI(gemini-api)是一个无状态、零依赖的命令行客户端,专为 AI 智能体构建,具有 shell 访问、脚本和 CI 管道。您的编码智能体可以使用它来生成文本和媒体、分析文件以及将任务委派给 Gemini 托管智能体。它适用于 Antigravity、Claude Code、Cursor 和任何标准 shell 环境。
每个功能都作为标准 shell 命令运行 Interactions API。从智能体子进程、终端或 CI 管道运行相同的命令:
# 1. Install on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
# 2. Set your API key
export GEMINI_API_KEY="YOUR_API_KEY"
# 3. Generate media, analyze a file, or launch a background managed agent
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
--agent deep-research-preview-04-2026 \
--background \
--stream=false
选择正确的 Gemini 工具 #
使用 gemini-api 当智能体或脚本需要时 打电话 直接从 shell 获取 Gemini,无需将 SDK 代码添加到您的项目中。使用 SDK 和 编码智能体设置 当你是 建筑物 Gemini 进入应用程序:
| 工具 | 它的作用 | 何时使用它 |
|---|---|---|
Gemini API CLI (gemini-api) | 从任何 shell 调用 Gemini 模型和托管智能体。 | 您的编码智能体、shell 脚本或 CI 作业需要生成媒体、分析文件或以零项目依赖性运行背景研究智能体。 |
| 谷歌 GenAI SDK | 将 Gemini 客户端库导入 Python、TypeScript、JavaScript、Go、Java 或 C# 代码。 | 您正在将 Gemini 功能构建到您的应用程序、后端服务或实时中 Live API 会议。 |
| Gemini Docs MCP & 技能 | 提供编码智能体实时文档搜索和当前 SDK 规则。 | 您的编码智能体正在编写导入 Google GenAI SDK 的应用程序代码。 |
它是如何运作的 #
原始 REST 调用和交互式 CLI 通常会导致智能体编码出现问题。 Base64 媒体填充上下文窗口,交互式提示会阻止子进程,陈旧的训练数据会导致出现幻觉标志。
保留四种设计选择 gemini-api 智能体可靠:
- 离线模式查找: 通行证
--usage打印命令树(在 KDL),或--schema打印 JSON Schema--body请求。 - 文件在磁盘上,路径在
stdout: 媒体和转录命令将文件写入磁盘并仅打印输出路径,从而使二进制数据脱离上下文。 - 试运行和结构化输出:
--dry-run验证输入、编辑凭据并离线预览 HTTP 请求。通行证-o json,-o toon, 或--jq用于机器可读的输出。添加--agent-mode返回结构化 JSON 错误stderr,并检查 退出代码 来处理故障。除非您通过,否则命令永远不会提示--interactive. - 默认无状态: 命令不保留隐藏的本地状态。显式链接多步骤工作
--previous-interaction-id, 上传的files/<id>URI,或后台交互ID。
与 -o json,媒体命令仍然将文件写入磁盘并将元数据打印到 stdout:
{
"kind": "image",
"mime_type": "image/jpeg",
"path": "/path/to/project/assets/db-icon.jpg",
"response_id": "v1_...",
"size_bytes": 2914159,
"status": "completed"
}
快速入门 #
安装 CLI,输入 gemini-api 在你的 PATH, 设置 GEMINI_API_KEY,并将使用规则添加到您的编码智能体中。
1. 安装二进制文件 #
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
要安装特定版本,请设置 GEMINI_VERSION 到发布标签:
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash
iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest
从以下网址下载适用于 macOS、Linux 和 Windows 的版本化存档 GitHub发布 并放置 gemini-api 在你的 PATH。使用预构建的档案来固定 Docker 映像和 CI 中的确切版本。
2. 配置认证并验证 #
创建一个 API 密钥 Google AI Studio (见 API 密钥)。套装 GEMINI_API_KEY 在您的 shell 和智能体的子进程环境中:
export GEMINI_API_KEY="YOUR_API_KEY"
在本地工作站上,您可以将密钥保存在操作系统钥匙串(macOS 钥匙串、Linux Secret Service 或 Windows 凭据管理器)中。通行证 --no-keyring 将密钥存储在 ~/.config/gemini-api/config.yaml 相反:
# Save to your OS keychain (or run gemini-api configure --interactive)
gemini-api configure --api-key "YOUR_API_KEY"
# Check the active credential source, then preview a request offline
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run
3. 提供您的智能体说明 #
将此代码片段添加到您的项目中 AGENTS.md, CLAUDE.md, .cursorrules,或系统提示,以便您的编码智能体知道如何使用 gemini-api:
## Gemini API CLI (`gemini-api`)
You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.
1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.
然后照常提示您编码智能体:
Build a landing page for our developer tool. Use Gemini to generate a hero
illustration and a 15-second welcome voiceover, and start a background Deep
Research agent to compare competing CLI onboarding flows. Wire the assets and
findings into the page.
命令 #
运行 gemini-api --help 列出所有命令,或 gemini-api explore 以交互方式浏览它们。
| 集团 | 命令 | 它的作用 |
|---|---|---|
| 创建 | image | 生成或编辑图像(-i),写入 JPEG 文件,并打印其路径。 |
| 创建 | tts | 合成 24 kHz 单声道 WAV 语音(一个或两个扬声器)并打印输出路径。 |
| 创建 | music | 生成音乐曲目或循环、写入音频文件并打印其路径。 |
| 创建 | video | 生成或编辑 MP4 剪辑并等待完成 (--async 立即返回 ID)。 |
| 创建 | generate | 生成文本并将其流式传输到 stdout (--stream=false 返回一个完整的结果)。 |
| 了解 | analyze | 回答有关 PDF、图像、音频、视频、CSV 和文本文件或公共 YouTube URL 的问题。 |
| 了解 | transcribe | 写入带有说话者标签、带时间戳的文字记录(md, text, json, 或 srt)并打印输出路径。 |
| 管理智能体 | agent | 运行托管智能体 (run, status, cancel, delete-interaction)并管理自定义智能体定义(create, list, get, delete). |
| 管理智能体 | environments, credentials, webhooks, triggers | 配置托管智能体的沙箱环境、存储的凭据、Webhook 交付和计划运行。 |
| 设置和文件 | configure, auth, whoami | 配置凭据和默认值,并显示活动的身份验证状态。 |
| 设置和文件 | files | 上传、列出、检查和删除 Files API 中的文件。 |
| 设置和文件 | models | 列出可用型号。 |
工作流程 #
每个命令默认都有一个适合其任务的模型。通行证 --model (-m)选择不同的模型。运行 gemini-api models 列出可用选项。
图像生成和编辑 #
智能体构建 Web 或移动 UI 可以生成占位符、图标和英雄图像 Nano Banana。将生成的路径传回 -i 编辑图像:
# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path
HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \
--aspect-ratio 16:9 \
--image-size 2K \
--out ./public/images/hero.jpg)
# Edit the generated image
gemini-api image "Add a winter scarf and soft snowfall outside the window" \
-i "$HERO_PATH" \
--out ./public/images/hero-winter.jpg
通行证 -i 多次组合参考图像,例如角色和风格指南。
语音合成 #
gemini-api tts 合成 24 kHz WAV 音频以用于 UI 提示、辅助功能预览和解说演练。默认语音是 Kore;选择另一个 --voice。对于两个说话者的对话,在提示中标记每个回合并将说话者映射到语音:
gemini-api tts "Build succeeded. All integration tests passed." \
--voice Aoede \
--out ./public/audio/build-ok.wav
gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \
--multi-speaker "Alice=Kore,Bob=Puck" \
--out ./public/audio/release-intro.wav
音乐和视频 #
创作原创曲目 Lyria,并生成 MP4 剪辑 Gemini Omni:
gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \
--out ./public/audio/bg-loop.mp3
gemini-api video "A drone shot of a mountain landscape at sunrise." \
--aspect-ratio 16:9 \
--resolution 1080p \
--out ./public/video/mountain-sunrise.mp4
默认情况下, video 命令等待生成完成并将 MP4 文件写入磁盘。通行证 --async 立即返回交互 ID,然后运行 gemini-api video --resume <id> --out <path> 稍后。通行证 -i 使现有图像动起来。
文本生成 #
gemini-api generate 将文本流式传输至 stdout:
gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."
添加 --stdin 将文本输入到提示中。通行证 --previous-interaction-id 继续之前的互动。
文档分析和转录 #
analyze 回答有关 PDF、电子表格、屏幕截图、音频和视频文件以及公共 YouTube URL 的问题。 transcribe 写入格式化的转录本(md, text, json, 或 srt) 到磁盘:
gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md
gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt
通行证 -i 多次到 analyze 比较文件,例如之前和之后的屏幕截图。
gemini-api 内联发送最大为 14 MB 的本地文件(base64 编码后为 20 MB)。对于较大的文件,请使用以下命令上传一次 files upload --wait 并重新使用返回的 files/<id> 网址:
FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)
gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json
运行和管理智能体 #
您的编码智能体可以将多步骤研究或沙盒任务委托给 Gemini 托管智能体,例如 Deep Research 智能体。通行证 --background --stream=false 立即获取交互 ID,而不是保持流打开:
# Launch a Deep Research job in the background and capture its interaction ID
RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \
--agent deep-research-preview-04-2026 \
--background \
--stream=false \
--jq '.id')
# Check status or fetch the finished result while continuing other work
gemini-api agent status "$RESEARCH_ID" -o json
运行 gemini-api agent cancel <id> 停止正在运行的作业。您还可以启动 Antigravity 智能体 在远程沙箱中 agent run,或管理 定制智能体 使用 agent create, list, get, 和 delete。参见 环境 配置智能体沙箱。
自定义请求机构 #
对于没有专用标志的选项,传递一个原始的 Interactions API JSON 有效负载 --body (内联或作为 @file.json)。通行证 --body 设置 response_format 模式、函数调用工具、 generation_config, 或 "store": false。运行 gemini-api <command> --schema 首先检查有效字段:
# Inspect the JSON Schema for the request body
gemini-api generate --schema > generate-schema.json
# Return schema-constrained JSON and skip storing the interaction
cat logs.txt | gemini-api generate "Extract every error message from these logs." \
--stdin \
--body '{
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "object",
"properties": {"errors": {"type": "array", "items": {"type": "string"}}},
"required": ["errors"]
}
},
"store": false
}'
--body 与命令标志合并。如果两者设置相同的键,则命令失败并显示退出代码 2 因此冲突的输入很快就会失败。
退出代码 #
每个命令都会返回一个键入的退出代码,因此脚本和智能体可以处理故障而无需解析错误文本。例如, 3 表示身份验证问题,并且 2 表示命令语法无效:
| 代码 | 含义 |
|---|---|
0 | 命令成功。 |
1 | 运行时或 API 错误,例如网络故障、速率限制或后台作业失败。 |
2 | 使用或验证错误,例如未知标志、丢失输入或重复 --body 关键。 |
3 | 身份验证或授权失败,例如API 密钥或token丢失或无效。 |
运行 gemini-api --help-global 列出每个命令共享的全局标志(身份验证、输出、网络和诊断)。
限制 #
- 流命令(
generate和agent run) 要求--stream=false当与-o json或--jq返回单个 JSON 响应对象。 - 内联
-i文件输入上限为 14 MB 的原始文件数据(20 MB 请求负载,包括 base64 编码)。上传大文件gemini-api files upload。 Files API 在 48 小时后删除上传的文件。 gemini-api支持标准 HTTP 请求、SSE 流和异步轮询,而不是双向 WebSocket。对于实时语音和视频流,请使用 Live API 与 谷歌 GenAI SDK.