目次
Googleは2026年10月27日、やスクリプト、からGemini を呼び出す「Gemini API （gemini-api）」をベータ公開しました。対象は、アプリへを組み込む前にモデルやメディア生成を試したい開発者、既存のコーディングエージェントへGeminiの機能を追加したいチーム、シェル処理として再現可能なAI工程を作りたい運用担当者です。
導入判断の要点は、これが対話型のコーディングエージェントではなく、Interactions APIを標準コマンドとして呼ぶ無状態のクライアントだという点です。画像や音声はファイルへ保存してパスを返し、出力、終了コード、ドライランを自動処理へ組み込めます。一方でベータ版には破壊的変更の可能性があるため、CIでは版を固定し、、保存データ、失敗時の再実行を明示的に管理する必要があります。本記事は公式ガイド、Interactions API資料、公式を2026年11月3日に確認した実装解説で、コマンドの実測結果ではありません。
スポンサーリンク
Gemini CLIやAgents CLIとは役割が違う
名称が近いツールを先に分けておくと、採用判断が簡単になります。gemini-apiは、シェルからGeminiモデル、メディア生成、ファイル解析、Managed Agentsを直接呼び出すためのAPIクライアントです。公式資料は「stateless（無状態）」を特徴に挙げ、コマンド間の文脈を暗黙に保持しません。継続が必要なら--previous-interaction-id、Files APIのURI、バックグラウンド実行のIDを呼び出し側が受け渡します。
| 選択肢 | 主な用途 | 向いている場面 |
|---|---|---|
| Gemini API CLI | シェルからAPI機能を一回ずつ呼ぶ | コーディングエージェント、CI、検証スクリプト |
| Google GenAI SDK | アプリのコードへGemini機能を組み込む | 、Web機能、リアルタイム処理 |
| Gemini CLI | 対話しながらコードやプロジェクトを扱う | 人が端末で進める開発作業 |
| Google Agents CLI | エージェントの作成・評価・配備を共通化する | Agent EngineやCloud Runを含むライフサイクル管理 |
つまり、既にCodexやClaude Codeなどを使っているチームが、別の対話環境へ移らずGeminiの画像生成や文書解析、Deep Researchを呼びたい場合にgemini-apiが候補になります。アプリ本体が毎リクエストでGeminiを使うならSDKの方が型、再試行、接続管理を実装しやすく、CLIを子プロセスとして常駐サービスへ組み込む理由は弱くなります。
エージェント向けに設計された四つの境界
公式ガイドが挙げる設計上の工夫は、単にコマンド数が多いことではありません。第一に、--usageでコマンドツリー、--schemaで--body用JSON Schemaをオフライン表示できます。エージェントが記憶だけで存在しないフラグを作るのを避け、実行前に現在のバイナリ自身へ問い合わせられます。
第二に、画像・音声・動画・文字起こしの成果物をディスクへ書き、標準出力にはパスやを返します。Base64を会話へ流してコンテキストを消費する構成を避けられます。第三に、--dry-runは入力を検証し、資格情報を伏せたリクエストをオフラインでプレビューします。-o json、-o toon、--jq、--agent-modeと終了コードを使えば、標準出力と標準エラーを機械的に判定できます。
第四が無状態実行です。便利な履歴が隠れていないため、同じ入力から同じ工程を再構成しやすい反面、処理IDを保存し忘れると後続処理を継続できません。背景実行したManaged Agentは、agent runが返すIDをジョブの成果物へ保存し、agent statusで確認し、不要になったInteractionは削除するところまで設計します。
スポンサーリンク
導入は版固定とドライランから始める
macOSとでは公式インストールスクリプト、WindowsではPowerShell、ほかにGoまたはGitHub Releasesのバイナリを利用できます。自動化では@latestや毎回変わるインストール先を避け、リリースタグとチェックサムを固定します。公式ガイドも、ベータ版はマイナー更新で破壊的変更が起こり得るとして、エージェント環境とCIで特定版を固定するよう求めています。
# バージョンを固定して導入する例
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh \
| GEMINI_VERSION=<release-tag> bash
# 認証元とリクエスト形を確認する
gemini-api whoami
gemini-api generate "接続確認" --dry-run -o jsonAPIキーはローカルならOSのキーチェーン、CIならリポジトリ外のストアから注入します。--no-keyringでは設定ファイルへ保存できるため、共有ランナーや成果物へ設定ディレクトリを含めないことも確認します。ドライランは秘密を伏せますが、入力ファイルや自体を公開してよいという意味ではありません。ジョブログへ残す項目を、コマンド全文ではなくモデル、処理種別、Interaction ID、終了コード、成果物パスに絞ると扱いやすくなります。
CIでは標準出力を契約として扱う
自動処理で重要なのは、自然文を次の工程へそのまま渡さないことです。たとえば文書解析なら、ストリーミングを止めてJSONで受け、必須フィールドと終了状態を検証します。メディア生成なら、返されたパスが許可した作業ディレクトリ内にあり、期待する拡張子・容量・個数かを確認してからへ渡します。CLIが成功しても、生成物が要件を満たしたことまでは証明されません。
set -euo pipefail
result=$(gemini-api analyze -i ./spec.pdf \
"変更点をJSONで整理" --stream=false -o json)
status=$(printf '%s' "$result" | jq -r '.status')
test "$status" = "completed" || exit 1
printf '%s' "$result" > ./artifacts/gemini-analysis.json上の例は処理の形を示す仮想例です。実際のレスポンス構造は固定したCLI版の--schemaと出力を確認し、値の検証を追加してください。タイムアウトやHTTP 429、5xxで再試行する場合も、画像・動画・Managed Agentの二重作成を避ける必要があります。実行前に生成物の有無と保存したInteraction IDを調べ、状態確認で再開できる処理と、新規作成が必要な処理を分けます。
スポンサーリンク
Interactions APIの保存設定もCLIの外で判断する
gemini-api自体はローカル状態を隠し持ちませんが、基盤のInteractions APIは別です。Googleの資料では、Interactions APIは既定でリクエストを保存し、previous_interaction_idによるサーバー側の状態管理を利用できます。保存を望まない処理ではstore=falseを指定し、会話継続や効率を優先する処理では保存期間と削除手順を確認します。「CLIが無状態」と「API側にデータを保存しない」を同じ意味にしないことが重要です。
また、Interactions APIは2026年6月から一般提供され、新規プロジェクトに推奨されていますが、Gemini API CLIはベータです。基盤APIの提供状態だけを見てCLIの互換性まで安定したと判断せず、バイナリ更新時には--usage、--schema、代表コマンドのドライラン、JSONパーサーの回帰テストを実行します。
採用前に小さな評価ジョブを作る
- 固定したCLI版で、必要なモデルとコマンドが列挙できるか
- APIキーをジョブログ、成果物、キャッシュへ残さず注入できるか
- ドライラン、JSON出力、終了コードをCIが正しく判定できるか
- 生成ファイルの保存先、形式、容量を後段で検証できるか
- Interaction IDを保存し、再試行時の二重作成を避けられるか
store=falseを含むデータ保存方針を用途別に決めたか- SDKへ移す条件を、呼び出し頻度、型、監視、遅延から定義したか
試行では、文書一件の解析や画像一枚の生成など、失敗しても影響が小さい工程を選びます。成功率だけでなく、入力検証で止まった件数、再試行回数、成果物の不採用率、エージェントが誤ったフラグを提案した回数も記録すると、SDK直書きや専用ワークフローと比較できます。シェルから呼べる手軽さが、運用の可視性と再現性につながる場合に採用価値があります。
一つのバイナリでも権限は用途別に分ける
CLIにはテキスト生成だけでなく、画像、音声、音楽、動画、文字起こし、ファイル管理、Managed Agentsの環境・資格情報・・トリガー管理まで含まれます。ただし、すべてを一つのAPIキーと一つのCIジョブへまとめる必要はありません。文書解析ジョブ、メディア生成ジョブ、Managed Agent管理ジョブを分け、使うコマンド、入力元、出力先、予算を個別に定義します。利用できるモデルはgemini-api modelsで実行時に確認し、資料にある例を自環境で常に利用できると仮定しません。
特にenvironments、credentials、webhooks、triggersは、単発生成より長く残る設定を扱います。無状態のコマンドでも、変更対象のサーバー資源は永続します。作成・更新・削除を行う工程にはレビューを置き、読み取りや生成だけの工程と分離します。CLI採用の評価では、便利なコマンドの数より、必要な機能だけを許可した実行単位を作れるかを確認してください。
関連記事
スポンサーリンク
