Gemini 中文指南
获取 API 密钥 ↗

Gemini API CLI

↓ 下载 MarkdownInteractions API

Gemini API CLI(gemini-api)是一个无状态、零依赖的命令行客户端,专为 AI 智能体构建,具有 shell 访问、脚本和 CI 管道。您的编码智能体可以使用它来生成文本和媒体、分析文件以及将任务委派给 Gemini 托管智能体。它适用于 Antigravity、Claude Code、Cursor 和任何标准 shell 环境。

每个功能都作为标准 shell 命令运行 Interactions API。从智能体子进程、终端或 CI 管道运行相同的命令:

bash
# 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:

json
{
  "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. 安装二进制文件 #

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

要安装特定版本,请设置 GEMINI_VERSION 到发布标签:

bash
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash

2. 配置认证并验证 #

创建一个 API 密钥 Google AI Studio (见 API 密钥)。套装 GEMINI_API_KEY 在您的 shell 和智能体的子进程环境中:

bash
export GEMINI_API_KEY="YOUR_API_KEY"

在本地工作站上,您可以将密钥保存在操作系统钥匙串(macOS 钥匙串、Linux Secret Service 或 Windows 凭据管理器)中。通行证 --no-keyring 将密钥存储在 ~/.config/gemini-api/config.yaml 相反:

bash
# 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:

markdown
## 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 编辑图像:

bash
# 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。对于两个说话者的对话,在提示中标记每个回合并将说话者映射到语音:

bash
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:

bash
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:

bash
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) 到磁盘:

bash
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> 网址:

bash
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,而不是保持流打开:

bash
# 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 首先检查有效字段:

bash
# 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.

后续步骤 #

搜索标题、API 名称或正文内容