2026.10.29 AI

Gemini API CLIとは？gemini-apiの導入・使い方とGemini CLIとの違い【2026年10月】

Q: gemini-apiのバージョンはどう確認し、どう上げればよいですか？

インストール済みの版を確認するコマンドは gemini-api --version です。上げるときは、GitHub の Releases で変更点を読み、破壊的変更の記載がないかを見てから、install.sh に GEMINI_VERSION を指定するか go install の @ の後ろを書き換えます。CIの設定ファイルで版を1か所にまとめておくと、上げ下げが1行の変更で済みます。

Gemini API CLIとは？gemini-apiの導入・使い方とGemini CLIとの違い【2026年10月】

Gemini API CLI は、Google が2026年10月27日にオープンソースのベータ版として公開した gemini-api コマンドです。Gemini API のリリースノートは、AIコーディングエージェント、スクリプト、CIパイプライン向けの「状態を持たず依存関係のないコマンドラインクライアント」と紹介しています。テキストや画像・音声・動画の生成、ファイルの分析、Deep Research などのマネージドエージェントの実行を、シェルの1行で呼び出せます。

本記事では、名前の似た Gemini CLI との違い、OS別のインストールとAPIキーの設定、よく使うコマンド、GitHub Actions に組み込む設定例、業務で採用してよい条件を扱います。Gemini API そのものの仕組みや料金の全体像はGemini APIとは？できること・料金・始め方とInteractions APIの最小コードで解説しています。版番号とコマンドの記載は、2026年10月29日時点の公式情報を根拠としたものです。

まとめ：gemini-apiはエージェントとCIからGemini APIを呼ぶ1行コマンド

gemini-api は Interactions API の機能をシェルコマンドにしたクライアントです。対話画面を持たず、1回の実行で1つの処理を返します。
Gemini CLI（gemini）とは別の製品です。Gemini CLI は人が対話しながらコードを書かせるエージェントで、gemini-api は他のプログラムやエージェントから呼ばれる部品です。
インストールは install.sh・install.ps1・go install の3通り。認証は GEMINI_API_KEY か OS のキーチェーンです。
2026年10月29日時点の最新は v0.4.4 です。マイナー版の間でも破壊的変更があるため、CIでは版を固定します。
検証用のスクリプトやCIの補助処理には向きますが、本番の業務システムから呼ぶ処理は SDK で実装する方が安全です。

Gemini API CLIとは：2026年10月27日ベータ公開のgemini-api

Interactions APIを1コマンドで呼ぶ状態を持たない依存なしのクライアント

公式のCLIドキュメントによると、gemini-api の各機能は Interactions API の上で動く標準的なシェルコマンドとして作られています。Interactions API は2026年6月に一般提供となった Gemini API の新しい呼び出し口で、モデルの呼び出しとエージェントの実行を同じ形式で扱います。

「状態を持たない」とは、会話の履歴を手元に保存しないという意味です。続きの質問をしたいときは、前回の応答の id を --previous-interaction-id に渡します。実行ファイルは Go で書かれた単体のバイナリで、Node.js や Python の実行環境を入れずに動きます。

想定する使い手は人よりもエージェントです。公式ドキュメントは Antigravity、Claude Code、Codex、Cursor などシェルを使えるエージェントから呼ぶ前提で、出力をJSONにする -o json、エラーをJSONで返す --agent-mode、送信内容を通信せずに確かめる --dry-run を備えています。

類似名のGemini CLI・Antigravity CLIとの役割を3製品で比較

Google のコマンドラインツールは似た名前が3つあり、検索結果でも混ざって表示されます。役割で分けると次のとおりです。

項目	Gemini API CLI	Gemini CLI	Antigravity CLI
コマンド名	gemini-api	gemini	agy
主な使い手	エージェント・スクリプト・CI	人（対話型）	人（対話型）
役割	APIを呼ぶ部品	コーディングエージェント	コーディングエージェント
2026年10月の状態	ベータ（v0.4.4）	個人無料枠は停止	Gemini CLIの後継
実装言語	Go	TypeScript（Node.js）	Go

Gemini CLI は2026年6月18日に Google ログインの個人無料枠が停止し、後継として Antigravity CLI が案内されています。経緯と移行の手順はGemini CLIは終了した？個人向け停止後も使える条件とAntigravity CLIとの違い・移行手順、agy の導入はAntigravity CLI（agy）の使い方にまとめています。gemini-api はこれらの後継でも代わりでもなく、Claude Code や agy の中から呼ばれる道具という位置づけです。

gemini-apiのインストールとAPIキー設定：OS別の導入と動作確認

install.sh・install.ps1・go installの3通りと版固定の例

公式ドキュメントが示す導入方法は次の3通りです。各OSでのインストールと、バージョンを固定する場合の書き方を示します。GitHub の Releases には macOS・Linux・Windows 向けのビルド済みバイナリもあり、Docker イメージやCIで版を厳密に固定するときはこちらが推奨されています。

# macOS / Linux（最新版）
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# macOS / Linux（版を固定する場合）
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=v0.4.4 bash

# Windows（PowerShell）
iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

# Go（main ブランチのビルドは Go 1.26.10 以上）
go install github.com/google-gemini/gemini-api-cli/cmd/[email protected]

# 入ったか確かめる
gemini-api --version

リポジトリの README によると、ライセンスはコードが Apache License 2.0 です。現時点では外部からのプルリクエストを受け付けておらず、不具合の報告は Issues で受けています。Releases を見ると、v0.3.0 で TypeScript から Go へ書き直されて後方互換が切れ、v0.4.0 でも複数の値を取るフラグが JSON 配列の形式に変わりました。@latest のまま使うと、この種の変更を知らないうちに取り込みます。

GEMINI_API_KEYとOSキーチェーンの選択とwhoami・dry-run確認

認証は Gemini API のAPIキーで行います。手元のPCでは OS のキーチェーン（macOS のキーチェーン、Linux の Secret Service、Windows の資格情報マネージャー）に保存し、CIやコンテナでは環境変数 GEMINI_API_KEY で渡すのが基本の分け方です。

# 手元のPC：キーチェーンに保存する
gemini-api configure --api-key "YOUR_API_KEY"

# CI・コンテナ：環境変数で渡す（シークレットストアから注入する）
export GEMINI_API_KEY="YOUR_API_KEY"

# どこから認証情報を読んでいるかを表示する
gemini-api whoami

# 通信せずにリクエストの中身だけを確かめる（キーは伏せて表示される）
gemini-api generate "Confirm CLI setup in one sentence." --dry-run

キーチェーンを使えない環境では --no-keyring を付けると ~/.config/gemini-api/config.yaml に保存されますが、平文のファイルになる点に注意してください。キーの発行手順と、2026年5月以降に作るキーが auth key に変わった点はGemini APIキーの取得方法：AI Studioでの発行・環境変数・制限と漏洩時の失効で解説しています。

gemini-apiで試すコマンド：テキスト生成・ファイル分析・画像と音声の生成

generateとstdin・bodyでログからエラー一覧をJSONで取り出す例

テキスト生成は generate です。v0.4.0 以降の既定モデルは gemini-3.8-flash で、-m で変えられます。標準入力を読む --stdin と、APIに渡すリクエスト本体を直接書く --body を組み合わせると、ログからエラーだけを JSON で取り出せます。

# --body に書ける項目を JSON Schema で確認する
gemini-api generate --schema > generate-schema.json

# ログからエラーメッセージを JSON 配列で取り出す（保存させない）
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
  }'

"store": false は、リクエストを Google 側に保存させない指定です。Interactions API は既定で保存する設定で、2026年10月26日からは有料枠の新規プロジェクトで従来の Generate Content API も既定で保存するよう変わりました。社内のログを流すなら、この1行を外さないでください。なお、--body と通常のフラグで同じ項目を指定すると、終了コード2で止まります。

analyze・transcribeでのPDF・会議動画の分析とfiles upload

analyze は PDF・画像・音声・動画・CSV・テキスト・公開中の YouTube の URL に質問するコマンドです。transcribe は話者ラベルとタイムスタンプ付きの文字起こしを md・text・json・srt で書き出します。

手元のファイルをそのまま送れるのは、元のデータで14MB（Base64に変換後で20MB）までです。それより大きい会議の録画などは、Files API へ先にアップロードし、返ってきた files/ で始まるURIを使い回します。アップロードしたファイルは48時間で消えるため、翌週に同じ動画を分析するならアップロードからやり直しになります。

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

image・tts・videoで素材を書き出し保存先のパスを次の処理へ渡す使い方

画像の image、音声合成の tts、楽曲の music、動画の video は、生成したファイルを保存して標準出力には保存先のパスだけを返します。パスを変数に受ければ、次のコマンドで編集の元画像に使えます。

HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop" \
  --aspect-ratio 16:9 --image-size 2K --out ./public/images/hero.jpg)
gemini-api image "Add a winter scarf" -i "$HERO_PATH" --out ./public/images/hero-winter.jpg

gemini-api tts "Build succeeded. All integration tests passed." \
  --voice Aoede --out ./public/audio/build-ok.wav

tts の出力は 24kHz・モノラルの WAV で、既定の声は Kore です。動画は完了まで待つのが既定で、--async を付けるとIDだけを先に返し、後から --resume で受け取れます。音声合成をアプリに組み込むときのモデル選びと料金はGemini API TTSの使い方で扱っています。

Deep Researchなどの実行手順：gemini-api agentによる調査

agent run –backgroundのID取得とstatusによる結果回収手順

agent サブコマンドは、Google 側で動くマネージドエージェントに仕事を渡します。代表がDeep Research エージェントで、複数の情報源を調べて出典付きの報告を返します。調査には数分以上かかるため、接続を開いたまま待たず、--background で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')

# 進み具合と結果を JSON で受け取る
gemini-api agent status "$RESEARCH_ID" -o json

# 途中で止める
gemini-api agent cancel "$RESEARCH_ID"

エージェントIDは時期によって入れ替わります。リリースノートでは deep-research-pro-preview-12-2025 が2026年10月23日に停止し、deep-research-preview-04-2026 か deep-research-max-preview-04-2026 への切り替えが案内されました。スクリプトにIDを直書きするなら、停止予定の告知を月に一度は確かめる運用にしておきます。このほか、隔離された実行環境（environments）や定期実行（triggers）、完了時の通知（webhooks）も同じCLIから設定できます。

CIとコーディングエージェントへの組み込み：終了コード・JSON出力・版固定

GitHub Actionsで版を固定しシークレットからキーを渡すワークフロー例

CIで使うときに押さえるのは、版の固定、キーの渡し方、終了コードによる分岐の3点です。gemini-api の終了コードは、0が成功、1が実行時またはAPIのエラー（通信障害・レート制限など）、2が使い方や入力の誤り、3が認証の失敗です。次の例は、プルリクエストの差分を要約してファイルに残します。

# .github/workflows/pr-summary.yml
name: pr-summary
on: pull_request
jobs:
  summary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-go@v5
        with:
          go-version: "1.26"
      - name: gemini-api を版固定で入れる
        run: |
          go install github.com/google-gemini/gemini-api-cli/cmd/[email protected]
          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
      - name: 差分を要約する
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          git diff origin/${{ github.base_ref }}...HEAD \
            | gemini-api generate "この差分の変更点を日本語で5行に要約してください" \
                --stdin > summary.md || code=$?
          case "${code:-0}" in
            0) cat summary.md ;;
            3) echo "認証に失敗しました。シークレットを確認してください"; exit 1 ;;
            *) echo "要約をスキップしました（終了コード ${code}）" ;;
          esac

要約に失敗してもビルド全体は止めず、認証の失敗だけは止める作りにしています。AIの処理は補助なので、レート制限で落ちたときにマージまで止めてしまうと開発の流れが詰まります。エラーの中身を機械で読みたい場合は --agent-mode を付けると構造化JSONで標準エラーに出ますが、README によると標準出力の既定形式も TOON に変わるため、要約をそのまま Markdown で残す用途では付けていません。Claude をCIで動かす場合の構成と費用はClaude Code GitHub Actionsの導入と料金と比べると違いが分かります。

AGENTS.mdやCLAUDE.mdに書くエージェント向けの呼び出しルール4項目

公式ドキュメントは、AGENTS.md・CLAUDE.md・.cursorrules などに書いておく指示の例を載せています。要点は次の4つです。

使うコマンドは --help か --usage で選び、--body を組み立てる前に --schema で項目を確かめる。
初めて使う呼び出しは --dry-run -o json で中身を確かめてから実行する。
JSONを1つだけ受け取りたいときや --jq を使うときは --stream=false -o json を付ける。
メディア系のコマンドが返すパスと、generate や agent run が返す id を次の処理で使う。

3番目は忘れやすい制約です。generate と agent run は既定で結果を少しずつ流すため、--stream=false を付けないと -o json や --jq と組み合わせられません。エージェントが同じエラーを繰り返すときは、まずここを疑います。

gemini-apiを業務で採用する条件と見送る場面：ベータ版の扱い方

gemini-api は手軽ですが、ベータ版のコマンドラインツールである点は変わりません。どこまで任せるかを先に決めておくと、仕様変更で慌てずに済みます。生成AIを既存の業務システムへ組み込む設計を外部に相談する場合は、生成AI開発・AI受託開発のような開発支援を前提に範囲を決めてください。

採用してよい条件＝検証用スクリプトやCIの補助処理など止まっても困らない用途

モデルの出力を試す検証、開発者の手元での調べもの、CIでの差分要約やログの分類のように、止まっても業務が続く処理には向いています。Python や Node.js の環境を用意せずに済み、エージェントに渡す道具としても扱いやすいためです。

条件は2つです。版を固定すること。そして、版を上げるときに --dry-run で同じリクエストが組み立てられるかを確かめてから切り替えること。Releases では v0.3.0 と v0.4.0 が2日違いで続けて出ており、どちらもフラグや出力の形式が変わっています。

見送る場面＝本番の業務システムから直接呼ぶ処理と双方向の音声対話

受注データの登録や顧客への自動返信など、本番の業務システムから呼び出してエラーを細かく扱う処理は、CLIを経由させず公式の SDK で書きます。シェルを挟むと、タイムアウトや再試行の制御、入力の受け渡しで不具合の切り分けが難しくなり、ベータ版の仕様変更がそのまま本番に響きます。

双方向の WebSocket にも対応していません。音声でのリアルタイム対話や映像のストリーミングは、SDK から Live API を使う構成になります。

Gemini API CLIの導入と使い方に関するよくある質問と回答

gemini-api について調べるときに出てきやすい疑問に、公式情報の範囲で答えます。

Gemini API CLIは無料で使えますか？

CLI 自体は Apache License 2.0 のオープンソースで、入手に費用はかかりません。ただし、コマンドを実行するたびに Gemini API を呼ぶため、APIの利用料はそのまま発生します。無料枠の範囲なら課金されませんが、無料枠の入出力は製品の改善に使われる場合があります。モデル別の単価と無料枠の上限はGemini APIの料金と無料枠を確認してください。

Gemini CLIを入れていればgemini-apiは不要ですか？

役割が違うため、置き換えにはなりません。Gemini CLI は人と対話しながらコードを書くエージェントで、gemini-api はスクリプトやエージェントから1回ずつAPIを呼ぶ部品です。画像や音声の生成、Deep Research の実行をスクリプトに組み込みたいなら gemini-api、対話しながら開発を進めたいなら Gemini CLI か後継の Antigravity CLI を選びます。

Vertex AIのプロジェクトやサービスアカウントで認証できますか？

2026年10月29日時点の公式ドキュメントが案内している認証は、Gemini API のAPIキーを環境変数か OS のキーチェーンで渡す方法です。Vertex AI の認証情報で使う手順は記載されていません。Vertex AI 側で契約や監査の要件を満たす必要がある案件では、SDK で Vertex AI を呼ぶ構成を選んでください。両者の違いはVertex AIとGemini APIの違いで比べています。

gemini-apiのバージョンはどう確認し、どう上げればよいですか？

インストール済みの版を確認するコマンドは gemini-api --version です。上げるときは、GitHub の Releases で変更点を読み、破壊的変更の記載がないかを見てから、install.sh に GEMINI_VERSION を指定するか go install の @ の後ろを書き換えます。CIの設定ファイルで版を1か所にまとめておくと、上げ下げが1行の変更で済みます。

大きな動画ファイルを分析すると失敗するのはなぜですか？

手元のファイルを直接送れる上限は、元のデータで14MB（Base64変換後で20MB）です。これを超えると送信できません。先に gemini-api files upload <ファイル> --wait で Files API へアップロードし、返ってきたURIを -i に渡してください。アップロードしたファイルは48時間で削除されるため、日をまたぐ処理では再アップロードが必要です。