# Gemini API CLI

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

每个功能都作为标准 shell 命令运行 [Interactions API](/docs/interactions-overview)。从智能体子进程、终端或 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
```

{% callout type="note" %}
`gemini-api` 是一个开源测试版，与 [Interactions API](/docs/interactions-overview)。次要版本之间可能会发生重大更改。固定特定的 [发布版本](https://github.com/google-gemini/gemini-api-cli/releases) 在自动化智能体环境和 CI 管道中。
{% /callout %}

## 选择正确的 Gemini 工具  {% #choose-tool %}

使用 `gemini-api` 当智能体或脚本需要时 **打电话** 直接从 shell 获取 Gemini，无需将 SDK 代码添加到您的项目中。使用 SDK 和 [编码智能体设置](/docs/coding-agents) 当你是 **建筑物** Gemini 进入应用程序：

| 工具                                              | 它的作用                                                           | 何时使用它                                                           |
| ----------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
| **Gemini API CLI** (`gemini-api`)               | 从任何 shell 调用 Gemini 模型和托管智能体。                                  | 您的编码智能体、shell 脚本或 CI 作业需要生成媒体、分析文件或以零项目依赖性运行背景研究智能体。            |
| **[谷歌 GenAI SDK](/docs/libraries)**             | 将 Gemini 客户端库导入 Python、TypeScript、JavaScript、Go、Java 或 C\# 代码。 | 您正在将 Gemini 功能构建到您的应用程序、后端服务或实时中 [Live API](/docs/live-api) 会议。 |
| **[Gemini Docs MCP & 技能](/docs/coding-agents)** | 提供编码智能体实时文档搜索和当前 SDK 规则。                                       | 您的编码智能体正在编写导入 Google GenAI SDK 的应用程序代码。                         |

{% callout type="note" %}
`gemini-api` 是一个无状态的 API 客户端，而不是像智能体这样的交互式编码 `@google/gemini-cli`。你可以运行 `gemini-api` 任何编码智能体内。
{% /callout %}

## 它是如何运作的  {% #how-it-works %}

原始 REST 调用和交互式 CLI 通常会导致智能体编码出现问题。 Base64 媒体填充上下文窗口，交互式提示会阻止子进程，陈旧的训练数据会导致出现幻觉标志。

保留四种设计选择 `gemini-api` 智能体可靠：

- **离线模式查找：** 通行证 `--usage` 打印命令树（在 [KDL](https://kdl.dev)），或 `--schema` 打印 JSON Schema `--body` 请求。
- **文件在磁盘上，路径在 `stdout`:** 媒体和转录命令将文件写入磁盘并仅打印输出路径，从而使二进制数据脱离上下文。
- **试运行和结构化输出：** `--dry-run` 验证输入、编辑凭据并离线预览 HTTP 请求。通行证 `-o json`, `-o toon`, 或 `--jq` 用于机器可读的输出。添加 `--agent-mode` 返回结构化 JSON 错误 `stderr`，并检查 [退出代码](/docs/cli#exit-codes) 来处理故障。除非您通过，否则命令永远不会提示 `--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"
}
```

## 快速入门  {% #get-started %}

安装 CLI，输入 `gemini-api` 在你的 `PATH`, 设置 `GEMINI_API_KEY`，并将使用规则添加到您的编码智能体中。

### 1. 安装二进制文件  {% #install %}

{% tabs %}
{% tab label="macOS 和 Linux" %}
```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
```
{% /tab %}

{% tab label="Windows（PowerShell）" %}
```bash
iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex
```
{% /tab %}

{% tab label="Go" %}
```bash
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest
```
{% /tab %}

{% tab label="预构建的二进制文件" %}
从以下网址下载适用于 macOS、Linux 和 Windows 的版本化存档 [GitHub发布](https://github.com/google-gemini/gemini-api-cli/releases) 并放置 `gemini-api` 在你的 `PATH`。使用预构建的档案来固定 Docker 映像和 CI 中的确切版本。
{% /tab %}
{% /tabs %}

### 2. 配置认证并验证  {% #authentication %}

创建一个 API 密钥 [Google AI Studio](https://aistudio.google.com/apikey) （见 [API 密钥](/docs/api-key)）。套装 `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
```

{% callout type="warning" %}
治疗 `GEMINI_API_KEY` 作为一个秘密。在 CI 中，从秘密存储注入密钥，而不是将其提交到存储库或构建文件。
{% /callout %}

### 3. 提供您的智能体说明  {% #agent-instructions %}

将此代码片段添加到您的项目中 `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`.
```

然后照常提示您编码智能体：

```none
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.
```

## 命令  {% #commands %}

运行 `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`                                              | 列出可用型号。                                                                                                  |

## 工作流程  {% #workflows %}

每个命令默认都有一个适合其任务的模型。通行证 `--model` (`-m`）选择不同的模型。运行 `gemini-api models` 列出可用选项。

### 图像生成和编辑  {% #image %}

智能体构建 Web 或移动 UI 可以生成占位符、图标和英雄图像 [Nano Banana](/docs/image-generation)。将生成的路径传回 `-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` 多次组合参考图像，例如角色和风格指南。

### 语音合成  {% #tts %}

`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
```

### 音乐和视频  {% #music-video %}

创作原创曲目 [Lyria](/docs/music-generation)，并生成 MP4 剪辑 [Gemini Omni](/docs/video):

```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` 使现有图像动起来。

### 文本生成  {% #generate %}

`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 %}

`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
```

### 运行和管理智能体  {% #managed-agents %}

您的编码智能体可以将多步骤研究或沙盒任务委托给 [Gemini 托管智能体](/docs/agents)，例如 [Deep Research 智能体](/docs/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 智能体](/docs/antigravity-agent) 在远程沙箱中 `agent run`，或管理 [定制智能体](/docs/custom-agents) 使用 `agent create`, `list`, `get`, 和 `delete`。参见 [环境](/docs/agent-environment) 配置智能体沙箱。

## 自定义请求机构  {% #custom-bodies %}

对于没有专用标志的选项，传递一个原始的 [Interactions API](/docs/interactions-overview) 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` 因此冲突的输入很快就会失败。

## 退出代码  {% #exit-codes %}

每个命令都会返回一个键入的退出代码，因此脚本和智能体可以处理故障而无需解析错误文本。例如， `3` 表示身份验证问题，并且 `2` 表示命令语法无效：

| 代码  | 含义                                  |
| --- | ----------------------------------- |
| `0` | 命令成功。                               |
| `1` | 运行时或 API 错误，例如网络故障、速率限制或后台作业失败。     |
| `2` | 使用或验证错误，例如未知标志、丢失输入或重复 `--body` 关键。 |
| `3` | 身份验证或授权失败，例如API 密钥或token丢失或无效。      |

运行 `gemini-api --help-global` 列出每个命令共享的全局标志（身份验证、输出、网络和诊断）。

## 限制  {% #limitations %}

- 流命令（`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](/docs/live-api) 与 [谷歌 GenAI SDK](/docs/libraries).

## 后续步骤  {% #whats-next %}

- [编码智能体设置](/docs/coding-agents)
- [Interactions API](/docs/interactions-overview)
- [Gemini 托管智能体](/docs/agents)
- [gemini-api-cli 上 GitHub](https://github.com/google-gemini/gemini-api-cli)
