---
title: "Gemini API CLIとは？gemini-apiの導入・使い方とGemini CLIとの違い【2026年10月】"
url: "https://www.issoh.co.jp/tech/details/19046/"
published: 2026-10-29
updated: 2026-10-29
categories: ["AI"]
publisher: "株式会社一創"
---

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

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

本記事では、名前の似た Gemini CLI との違い、OS別のインストールとAPIキーの設定、よく使うコマンド、GitHub Actions に組み込む設定例、業務で採用してよい条件を扱います。Gemini API そのものの仕組みや料金の全体像は[Gemini APIとは？できること・料金・始め方とInteractions APIの最小コード](https://www.issoh.co.jp/tech/details/18759/)で解説しています。版番号とコマンドの記載は、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ドキュメント](https://ai.google.dev/gemini-api/docs/cli)によると、gemini-api の各機能は [Interactions API](https://ai.google.dev/gemini-api/docs/interactions-overview) の上で動く標準的なシェルコマンドとして作られています。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との違い・移行手順](https://www.issoh.co.jp/tech/details/7470/)、agy の導入は[Antigravity CLI（agy）の使い方](https://www.issoh.co.jp/tech/details/12220/)にまとめています。gemini-api はこれらの後継でも代わりでもなく、Claude Code や agy の中から呼ばれる道具という位置づけです。

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

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

公式ドキュメントが示す導入方法は次の3通りです。各OSでのインストールと、バージョンを固定する場合の書き方を示します。[GitHub の Releases](https://github.com/google-gemini/gemini-api-cli/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/gemini-api@v0.4.4

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

[リポジトリの README](https://github.com/google-gemini/gemini-api-cli) によると、ライセンスはコードが 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での発行・環境変数・制限と漏洩時の失効](https://www.issoh.co.jp/tech/details/18858/)で解説しています。

## 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](https://ai.google.dev/gemini-api/docs/files) へ先にアップロードし、返ってきた `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の使い方](https://www.issoh.co.jp/tech/details/7342/)で扱っています。

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

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

`agent` サブコマンドは、Google 側で動くマネージドエージェントに仕事を渡します。代表が[Deep Research エージェント](https://ai.google.dev/gemini-api/docs/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/gemini-api@v0.4.4
          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の導入と料金](https://www.issoh.co.jp/tech/details/7094/)と比べると違いが分かります。

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

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

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

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

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

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

### 採用してよい条件＝検証用スクリプトや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の料金と無料枠](https://www.issoh.co.jp/tech/details/18813/)を確認してください。

### 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の違い](https://www.issoh.co.jp/tech/details/18410/)で比べています。

### 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時間で削除されるため、日をまたぐ処理では再アップロードが必要です。

## 関連記事

- [Gemini APIとは？できること・料金・始め方とInteractions APIの最小コード【2026年10月】](https://www.issoh.co.jp/tech/details/18759/)：gemini-api の土台になる Gemini API と Interactions API の全体像です。
- [Gemini CLIは終了した？個人向け停止後も使える条件とAntigravity CLIとの違い・移行手順](https://www.issoh.co.jp/tech/details/7470/)：名前の似た対話型エージェント Gemini CLI の現状と移行先をまとめています。
- [Gemini APIキーの取得方法：AI Studioでの発行・環境変数・制限と漏洩時の失効【2026年10月】](https://www.issoh.co.jp/tech/details/18858/)：gemini-api に渡すAPIキーの発行と管理の手順です。
- [Gemini APIの料金と無料枠：モデル別単価・課金設定・費用の計算コード【2026年10月】](https://www.issoh.co.jp/tech/details/18813/)：CLIから呼んだ分の費用を見積もるときに使えます。
- [Claude Code GitHub Actionsの導入と料金｜@claude連携の設定・分単価とトークン課金](https://www.issoh.co.jp/tech/details/7094/)：CIにAIを組み込む別の構成として比べられます。

---

出典: [Gemini API CLIとは？gemini-apiの導入・使い方とGemini CLIとの違い【2026年10月】](<https://www.issoh.co.jp/tech/details/19046/>)（株式会社一創）