實測：2026-11-14 21:53（Asia/Taipei），macOS Apple Silicon
ts-m1，gemini-api 0.4.6。本文所有生成與 Agent 範例皆以--dry-run實際執行，沒有送出 Gemini API 請求、沒有模型費用，也沒有產出模型生成的媒體。適合 Taiwan／APAC developer community 與 GDE 工作坊使用。🎬 影音導讀
▶️ 70 秒完整導讀影片：
⚡ 13 秒 Shorts 精華：https://youtube.com/shorts/82-Z_Jq-ezQ
1. 引言與 2026 CLI 版圖重整
2026-06-18 是 Google 個人開發工具入口的分水嶺：Gemini CLI 對免費個人帳號及 Google AI Pro／Ultra（Google One）的服務移往 Antigravity CLI。這項改變有明確的帳號範圍，不能簡化為所有 gemini-cli 使用方式與企業服務全部消失。遷移背景可參考 Google 官方公告。
開發者可以採用雙軌架構：agy 作為大腦與 Agent 宿主，負責理解需求、規劃與持續工作；gemini-api 提供無狀態的多模態 API 原語，由宿主透過 shell 呼叫。這是工作分工的建議：也可以讓 Codex、Claude Code 或其他能執行 shell 的 Agent 使用同一支 binary。官方 repository 的定位正是替既有 Agent 提供 Gemini models 與 managed agents。
這裡的 stateless 指 CLI 本身不維護隱藏的對話狀態；Interactions API 仍可保留服務端 interaction、延續既有 ID，或執行背景工作。把「無狀態 CLI」理解成「服務端完全沒有狀態」會誤判這套架構。
2. 安裝與標準認證
gemini-api 是以 Go 建置的單一 binary；macOS／Linux 可使用官方安裝腳本：
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
command -v gemini-api
gemini-api --versionts-m1 安裝前找不到指令。腳本偵測 Darwin／arm64，因 /usr/local/bin 無寫入權限而選擇 /Users/jimmyliao/.local/bin/gemini-api，下載並安裝 v0.4.6。實測版本第一行是 gemini-api 0.4.6；build 時間換算台北為 2026-11-11 02:46:39。.zshrc 第 159、327、345 行已有 .local/bin 的 PATH 設定，登入 shell 也能解析到同一個 binary，這次沒有修改 .zshrc。若你的 shell 找不到指令，可加入：
export PATH="$HOME/.local/bin:$PATH"腳本的 latest 會隨時間變動；CI 可依 官方安裝文件 用 GEMINI_VERSION 指定 release。
標準認證可選環境變數或互動設定：
export GEMINI_API_KEY="YOUR_API_KEY"
gemini-api configure
gemini-api whoami上面是兩種設定方式的示意，不必同時使用。configure 可將 secret 儲存於 OS Keychain；--no-keyring 會改變儲存行為，不應在不知情時加入日常設定。本次沒有執行互動設定、讀取 Keychain 或寫入認證；每個測試子程序移除 GEMINI_API_KEY、GEMINI_ACCESS_TOKEN 等相關環境變數並設定 GEMINI_NO_KEYRING=true。whoami 實測顯示兩種 credentials 皆為 [unset]、API version 為 v1beta。它是設定來源診斷，不能當作真實 API 授權或 quota 成功證明。完整輸出見專案實測紀錄 experiments/01-cli-introspection/results.md。
3. 為什麼這是為 AI Agent 設計的 CLI？
Agent 容易使用過期旗標、把 binary 資料塞進 context，或卡在互動提示。這套 CLI 提供可離線發現的介面與檔案輸出，讓宿主在執行前先確認能力。
本機對官方文件頁執行 curl -sS -I https://aistudio.google.com/docs/cli，實際收到：
content-type: text/markdown; charset=utf-8
x-llms-txt: /llms.txt
link: </llms.txt>; rel="llms-txt", </llms-full.txt>; rel="llms-full-txt"這使 Agent 能沿著文件索引取得當前資訊。CLI 端則有：
gemini-api --usage # 完整 KDL command tree
gemini-api generate --schema # request body JSON Schema
gemini-api agent run --schema
gemini-api generate "Test prompt" --dry-run -o json--schema 不是所有子指令通用：本次 generate、image、video、agent run 成功；analyze、tts、transcribe 回傳 exit code 2 與 unknown flag: --schema。便利指令應先讀自身 --help，需要完整 request body 控制時再看 agent run 的 schema。
安全預演也有實證：使用明確的假測試字串作為 --api-key，輸出中的 X-Goog-Api-Key 為 [REDACTED]。這次沒有用真實金鑰做測試。預演只驗證 CLI 能建立 request，不代表 server 接受模型、權限或參數。
JSON 適合程式解析；TOON 是 CLI 支援的另一種結構輸出格式。但 v0.4.6 的 dry-run 兩者實際都輸出 JSON request envelope：
{"dry_run":true,"request":{"method":"POST","url":"https://generativelanguage.googleapis.com/v1beta/interactions","headers":{"Accept":["text/event-stream"],"Content-Type":["application/json"],"User-Agent":["google-genai-cli/0.4.6 gl-go/go1.26.10"]},"body":{"input":"Test prompt","model":"gemini-3.8-flash","stream":true}}}--jq 有支援，但預演不會真的套用篩選。本次 generate "Test prompt" --dry-run --jq '.body.model' 仍印出完整 envelope，並使 request 的 stream 變成 false。正常 API response 可依回應結構使用 --jq；如果目標是篩選預演本身，可交給外部 jq：
gemini-api generate "Test prompt" --dry-run -o json | jq -r '.request.body.model'原始假金鑰驗證與 HTTP headers 見標準流程實測 experiments/02-part1-standard-workflows/sample-dry-runs.md；HTTP response cookie 已省略。
4. 核心指令與多模態實戰
以下在實驗目錄執行；input.txt 是 64-byte 文字，silence.wav 是本機建立的 0.1 秒、16 kHz mono PCM 靜音 fixture。六種指令全部 dry-run 成功（exit code 0）。移除 --dry-run 後才會實際送出請求，並依模型／專案條件消耗 quota 或產生費用。
cd experiments/02-part1-standard-workflows
gemini-api generate "Test prompt" --dry-run --output-format json
gemini-api analyze -i input.txt "Summarize" --dry-run
gemini-api image "Minimalist cloud database icon" --out /tmp/gapi-test.jpg --dry-run
gemini-api tts "Welcome to the Taiwan developer community" --out voice.wav --dry-run
gemini-api transcribe -i silence.wav --out transcript.md --dry-run
gemini-api video "A cloud above Taipei" --out cloud.mp4 --dry-run所有預演都指向 POST https://generativelanguage.googleapis.com/v1beta/interactions。其 HTTP body 差異是理解多模態工作流的重點（下圖整理六種指令的預設 model 與 payload 關鍵）：
這些是 binary 的當前預設值，不是模型可用性測試。analyze 的檔案內容在預演顯示 "text":"<bytes:64>"；音訊顯示 "data":"<bytes:3244>"，避免把完整檔案／base64 塞進輸出。TTS 的精簡 body 如下，為便於閱讀摘錄實測欄位：
{
"generation_config": {"speech_config": [{"voice": "Kore"}]},
"input": [{"content": [{"text": "Welcome to the Taiwan developer community", "type": "text"}], "type": "user_input"}],
"model": "gemini-3.8-flash-tts",
"response_format": {"type": "audio"},
"store": false,
"stream": false
}--out 是 CLI 本機檔案處理選項，因此不會出現在上述 HTTP body。依實測 help，TTS 輸出為 24 kHz mono WAV，指定 .mp3 也會調整成 .wav；transcribe 支援 md、text、json、srt；video 正常執行會等待背景 interaction，--async 則先回傳 ID。這些媒體輸出契約來自 CLI help，本次沒有實際生成或下載檔案。
4.1 實戰情境貫穿（Part 1 視角）：從分鏡表到 9:16 AI Reels 短片的 6 步多模態管線
《15 秒看懂為什麼 AI Agent 需要多模態 CLI 工具箱》把原語串成版本控制工作流：generate --stdin 規劃 → image --aspect-ratio 9:16 --image-size 1K 首幀 → image -i 延續風格（也可依 help 使用 --previous-interaction-id 延續真實 interaction）→ video --aspect-ratio 9:16 --resolution 720p -i → tts --multi-speaker "Host=Kore,CoHost=Puck" → music、transcribe --format srt → analyze 安全區與設定 QA。六步共八次 CLI 呼叫。
可執行腳本為專案內的 examples/reels-storyboard-pipeline/run-reels-pipeline.sh，逐字證據見 examples/reels-storyboard-pipeline/dry-run-trace.md。實測 envelope 有 "dry_run":true；image 的 response_format 包含 "aspect_ratio":"9:16","image_size":"1K","mime_type":"image/jpeg","type":"image"；video 是 "background":true、"resolution":"720p"；TTS 的 speech_config.speakers 含 {"speaker":"Host","voice":"Kore"} 與 {"speaker":"CoHost","voice":"Puck"}。
fixtures/* 是本機合成測試輸入，非模型生成媒體；PNG 輸入顯示 "data":"<bytes:84>","mime_type":"image/png"，WAV 為 "data":"<bytes:6444>","mime_type":"audio/wav"。16×28 fixture 不是精確 9:16，只驗 MIME；正式請求比例由 flag 指定。八次均 Exit 0，沒有生成媒體。範例只渲染第一鏡影片與兩張首幀，不會自動剪成三鏡 15 秒成片；需另驗時長、混音、字幕與最終安全區。Step 1 回答也不會自動取代已版本控制的 storyboard。
Part 1 可執行範例程式碼
本機執行檔位於專案內 examples/part1-multimodal-cli/sample-part1-reels-primitives.sh。以下在本專案根目錄整段貼入執行；不需要 clone 公開 OSS repo，本次沒有建立公開 OSS repo。需要 bash、python3 與已安裝的 gemini-api 0.4.6；程式碼與本機腳本使用相同指令，只把腳本定位改為根目錄相對路徑。
所有 fixtures/* 均為本機合成 MIME 測試輸入，非模型生成媒體；dry-run 只驗 request，不生成成片。--schema 與 --schema --dry-run 都實測輸出 JSON Schema。
bash <<'PART_SAMPLE'
(
set +x
set -euo pipefail
cd examples/part1-multimodal-cli
unset GEMINI_API_KEY GEMINI_ACCESS_TOKEN GEMINI_ENVIRONMENT_KEY GEMINI_USER_PROJECT
export GEMINI_NO_KEYRING=true
R=../reels-storyboard-pipeline
echo '步驟：schema discovery（離線）' >&2
gemini-api video --schema --dry-run </dev/null
echo '步驟：分鏡、首幀與風格延續（fixtures 是本機合成 MIME 輸入）' >&2
gemini-api generate --stream=false --stdin '依簡報產出三鏡分鏡：' --dry-run < "$R/storyboard-brief.txt"
gemini-api image '台北科技 Reels 首幀' --aspect-ratio 9:16 --image-size 1K --output-mime-type image/jpeg --out /tmp/part1-scene1.jpg --dry-run </dev/null
gemini-api image '延續首幀風格' -i "$R/fixtures/scene1-keyframe.png" --aspect-ratio 9:16 --image-size 1K --output-mime-type image/jpeg --out /tmp/part1-scene2.jpg --dry-run </dev/null
echo '步驟：影片、雙人旁白、配樂與字幕' >&2
gemini-api video '首幀緩慢推進' --aspect-ratio 9:16 --resolution 720p -i "$R/fixtures/scene1-keyframe.png" --out /tmp/part1-scene1.mp4 --dry-run </dev/null
gemini-api tts --multi-speaker "Host=Kore,CoHost=Puck" -f "$R/dialogue.txt" --out /tmp/part1-voice.wav --dry-run </dev/null
gemini-api music '科技短片背景音樂' --out /tmp/part1-music.wav --dry-run </dev/null
gemini-api transcribe --format srt -i "$R/fixtures/voiceover-sample.wav" --out /tmp/part1-captions.srt --dry-run </dev/null
echo '步驟：首幀與分鏡 QA' >&2
gemini-api analyze -i "$R/fixtures/scene1-keyframe.png" -i "$R/storyboard.json" '檢查 Reels 安全區與分鏡一致性' --dry-run </dev/null
)
PART_SAMPLE5. Managed Agents 與 Self-Hosted Agent Substrate 展望
模型原語之外，CLI 也能啟動 Interactions API managed agent：
gemini-api agent run "Compare WebRTC SFU architectures" \
--agent deep-research-preview-04-2026 \
--background --stream=false --dry-run實測 request body 是：
{
"agent": "deep-research-preview-04-2026",
"background": true,
"input": "Compare WebRTC SFU architectures",
"stream": false
}這證明 CLI 能構造背景研究請求；沒有真正啟動研究工作、取得 interaction ID 或驗證專案開通資格。
我們也檢查 /tmp/gapi-research/google-gemini-gemini-api-cli-2030ff1/ 的原始碼快照。internal/sdk/models/interactions/ 除 Deep Research 外，還包含以下 typed config：
AntigravityAgentConfig：type:"antigravity"，含model、max_total_tokens，描述 server-side agent runtime。CodeMenderAgentConfig：實際 discriminator 為type:"code-mender"；含 FIND／FIX request、model 與 session 設定，用於漏洞探索、修補與驗證。DynamicAgentConfig：type:"dynamic"，允許額外屬性。
對應的 Interactions SDK 原始碼 可用來理解 request 型別；型別存在不等於所有帳號都能呼叫，也不等於本機 agy 登入能直接授權 API managed agent。
Self-Hosted Environments 文件 描述由服務端 Agent 推理、工具在自有 compute 執行的架構。單一 worker 模式使用 environments connect 與 scoped environment key；分離模式由可信任 control plane 執行 environments poll，再以短效 interaction lease token 啟動 environments serve，讓 sandbox 不必持有專案 API key。
其中 Agent Substrate 範例 提供 ate-gemini：controller 與 idle sweeper 管理生命週期，provision hook 建立或恢復 actor，actor daemon 再啟動一次性的 CLI worker。它使用 Kubernetes、gVisor actor、mTLS 與 gRPC；custom_config 可指定 atespace、template 與 egress policy。這是原始碼與文件導讀，本次未部署。
這裡有實際架構邊界：ate-gemini 不替 interaction 背後的使用者做應用層 authentication／authorization。若提供多租戶服務，應用必須自行檢查誰可以建立 interaction、使用哪些 atespace／template／egress 規則；mTLS 驗證元件身份不等於終端使用者 ACL。
6. 預告 Part 2：用 Google Account ADC 探索免 API key 工作流
不想在多台機器與容器放明文 GEMINI_API_KEY？下一篇將以 Google Account ADC 取得的 access token，搭配 GEMINI_ACCESS_TOKEN 與 --user-project 實測 OAuth 路徑，並比較 Free Tier／Paid Tier 以及 AI Pro／Ultra 的資格與限制。
這裡的「免金鑰」指免 API key，仍需管理短效 token 與 project 授權；ADC 不是本篇已驗證的原生自動登入功能。Google One 訂閱也不能直接推論成 Gemini API 額度。Part 2 應分別驗證認證、consumer project、billing 與 API entitlement，再依真實回應報告，不先承諾訂閱可以抵用 API 費用。
本文完整 command tree、schema、exit code 與 stdout／stderr 保存在專案內 experiments/01-cli-introspection/results.md，便於讀者重現及後續版本比較。
7. Live 實測補錄：2026-11-15 §4.1 Reels 管線實跑與費用帳本
我們已於 2026-11-15 00:20:54 → 00:24:23 Asia/Taipei (UTC+8) 在 gde-jimmyliao-redeem（Paid Tier）真實打通 §4.1 全部 8 步多模態 CLI 呼叫並以本地 ffmpeg 8.1 完成封裝：
全程零 Fallback：
gemini-3.8-flash（分鏡 & QA）、gemini-nano-banana-2.1（Scene 1 & Scene 2768x1376首幀延續）、gemini-omni-1.2-flash（5s720p圖生影片，$0.3527佔最大宗）、gemini-3.8-flash-tts（雙人語音9.44s）、lyria-3.5（全曲背景音樂159.48s）、gemini-3.5-transcribe（SRT 字幕）全部一次Exit 0。成本與呼叫次數：8 次生成/分析 + 4 次
$0agent status輪詢，合計44,934tokens、預估總成本$0.54853125 USD(~$0.5485)（Keyframe-First 護欄省去另 2 鏡影片約~$0.705 USD）。實測意外收穫：
gemini-api music --out bgm.wav實際回傳audio/mpeg(extension_mismatch: true)；gemini-3.5-transcribe將繁中口白「先驗首幀」辨識成簡中「先验手针」。完整單價公式與輸出檔請見專案內experiments/06-live-execution-and-cost-log/cost-and-call-ledger.md與examples/reels-storyboard-pipeline/output/final-reel.mp4。
