Gemini API CLI¶
Gemini API CLI(gemini-api)是一款無狀態、零相依性的命令列用戶端,專為具備 shell 存取權限的 AI 代理、指令碼與 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-api 是開源的 beta 版本,會隨 Interactions API 一同演進。次要版本之間可能出現破壞性變更。在自動化代理環境與 CI 管線中,請鎖定特定的發行版本。
選擇合適的 Gemini 工具¶
當代理或指令碼需要直接從 shell 呼叫 Gemini、又不想在專案中加入 SDK 程式碼時,請使用 gemini-api。當您要將 Gemini 建置進應用程式時,則請使用 SDK 與程式設計代理設定:
| 工具 | 功能 | 使用時機 |
|---|---|---|
Gemini API CLI(gemini-api) |
從任何 shell 呼叫 Gemini 模型與託管代理。 | 您的程式設計代理、shell 指令碼或 CI 工作需要在零專案相依性的情況下生成媒體、分析檔案,或執行背景研究代理。 |
| Google GenAI SDKs | 將 Gemini 用戶端程式庫匯入 Python、TypeScript、JavaScript、Go、Java 或 C# 程式碼。 | 您要將 Gemini 功能建置進應用程式、後端服務,或即時的 Live API 工作階段。 |
| Gemini Docs MCP & skills | 為程式設計代理提供即時文件搜尋與最新 SDK 規則。 | 您的程式設計代理正在撰寫匯入 Google GenAI SDK 的應用程式程式碼。 |
gemini-api 是無狀態的 API 用戶端,並非像 @google/gemini-cli 那樣的互動式程式設計代理。您可以在任何程式設計代理內執行 gemini-api。
運作方式¶
原始 REST 呼叫與互動式 CLI 經常為程式設計代理帶來問題:Base64 媒體會塞滿上下文視窗、互動式提示會卡住子行程,過時的訓練資料則會導致虛構的旗標。
四項設計抉擇讓 gemini-api 對代理而言保持可靠:
- 離線結構定義查詢:傳入
--usage可印出指令樹(以 KDL 表示),或傳入--schema印出--body請求的 JSON Schema。 - 檔案寫入磁碟、路徑印到
stdout:媒體與轉錄指令將檔案寫入磁碟,只印出輸出路徑,讓二進位資料不進入上下文。 - 預演與結構化輸出:
--dry-run可驗證輸入、遮蔽憑證,並離線預覽 HTTP 請求。傳入-o json、-o toon或--jq可取得機器可讀的輸出。加上--agent-mode可在stderr回傳結構化 JSON 錯誤,並查看結束碼來處理失敗。除非傳入--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
從 GitHub Releases 下載 macOS、Linux 與 Windows 的版本封存檔,並將 gemini-api 加入您的 PATH。在 Docker 映像與 CI 中,請使用預先建置的封存檔來鎖定確切版本。
2. 設定驗證並確認¶
在 Google AI Studio 建立 API 金鑰(請參閱 API 金鑰)。在您的 shell 與代理的子行程環境中設定 GEMINI_API_KEY:
export GEMINI_API_KEY="YOUR_API_KEY"
在本機工作站上,您可以將金鑰儲存在作業系統的鑰匙圈中(macOS Keychain、Linux Secret Service 或 Windows Credential Manager)。若要改將金鑰儲存在其他位置,請傳入 --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
請將 GEMINI_API_KEY 視為機密。在 CI 中,請從您的機密儲存空間注入該金鑰,不要將它提交到存放庫或建置檔案中。
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 以互動方式瀏覽。
| 群組 | 指令 | 功能 |
|---|---|---|
| Create | image |
生成或編輯圖片(-i),寫入 JPEG 檔案並印出其路徑。 |
| Create | tts |
合成 24 kHz 單聲道 WAV 語音(一或兩位講者)並印出輸出路徑。 |
| Create | music |
生成音樂曲目或循環片段,寫入音訊檔案並印出其路徑。 |
| Create | video |
生成或編輯 MP4 影片並等待完成(--async 會立即回傳 ID)。 |
| Create | generate |
生成文字並串流至 stdout(--stream=false 會回傳一個完整結果)。 |
| Understand | analyze |
回答關於 PDF、圖片、音訊、影片、CSV 與文字檔案,或公開 YouTube 網址的問題。 |
| Understand | transcribe |
寫入附講者標籤與時間戳記的轉錄稿(md、text、json 或 srt)並印出輸出路徑。 |
| Manage agents | agent |
執行託管代理(run、status、cancel、delete-interaction),並管理自訂代理定義(create、list、get、delete)。 |
| Manage agents | environments、credentials、webhooks、triggers |
設定託管代理的沙箱環境、已儲存憑證、webhook 傳遞與排程執行。 |
| Setup and files | configure、auth、whoami |
設定憑證與預設值,並顯示目前的驗證狀態。 |
| Setup and files | files |
在 Files API 中上傳、列出、檢視與刪除檔案。 |
| Setup and files | 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 創作原創曲目,並使用 Gemini Omni 生成 MP4 影片:
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 網址的問題。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> URI:
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> 可停止執行中的工作。您也可以用 agent run 在遠端沙箱中啟動 Antigravity 代理,或用 agent create、list、get 與 delete 管理自訂代理。請參閱環境以設定代理沙箱。
自訂請求主體¶
對於沒有專用旗標的選項,請使用 --body 傳入原始的 Interactions API JSON 酬載(行內或以 @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 金鑰或權杖遺失或無效。 |
執行 gemini-api --help-global 可列出每個指令共用的全域旗標(驗證、輸出、網路與診斷)。
限制¶
- 串流指令(
generate與agent run)必須使用--stream=false,與-o json或--jq併用時才能回傳單一 JSON 回應物件。 - 行內
-i檔案輸入的原始檔案資料上限為 14 MB(包含 base64 編碼的請求酬載為 20 MB)。大型檔案請使用gemini-api files upload上傳。Files API 會在 48 小時後刪除上傳的檔案。 gemini-api支援標準 HTTP 請求、SSE 串流與非同步輪詢,不支援雙向 WebSocket。即時語音與影片串流請使用搭配 Google GenAI SDKs 的 Live API。