Gemini API CLI：コーディングエージェントから画像・動画・PDF・ディープリサーチ用にGeminiを呼び出そう

Gemini API CLI（gemini-api）は、Google が提供する Gemini API 向けのオープンソースのコマンドラインクライアントで、Claude Code、Codex、Cursor、Antigravity といったコーディングエージェント向けに作られています。Go のバイナリを 1 つインストールし、GEMINI_API_KEY を設定すれば、エージェントは画像、動画、音声、音楽を生成し、PDF や録音を分析し、音声を SRT に文字起こしし、バックグラウンドで Deep Research を起動できます。

以下では、インストール、認証、エージェントが実行するコマンド、Gemini CLI との違い、そして Apidog CLI との組み合わせ方について説明します。すべてのフラグは、2026 年 10 月 30 日にリリースされたバージョン 0.4.5 の gemini-api --help からそのまま引用しています。

Gemini API CLI とは？

Gemini API CLI は、Google の Interactions API 向けのステートレスな単一バイナリのクライアントです。各コマンドは 1 回の HTTP 呼び出しです。プロンプトを入力すると、ファイルパス、文字起こし、分析結果、またはインタラクション ID が出力されます。これは、タスクに Gemini が必要になったときに、あなたが既に使っているエージェントが呼び出すツールです。

Google の公式ドキュメントページでは、これを「Interactions API とともに進化するオープンソースのベータリリース」と呼んでいます。コードは Apache 2.0 の下で google-gemini/gemini-api-cli にあり、macOS、Linux、Windows で動作します。

以下は、0.4.5 で gemini-api --help が表示する内容で、各コマンドのデフォルトモデルも併記しています。

Gemini API CLI と Gemini CLI の比較

名前が似ているので、ここで違いを整理します。Gemini CLI（@google/gemini-cli）は、対話型のコーディングエージェントであり、チャットする Claude Code の代替です。Gemini API CLI（gemini-api）にはエージェントループがまったくありません。これは別のエージェントが実行するツールです。

Claude Code や Codex で作業していて、そのワークフロー内で Gemini のメディアモデルやリサーチモデルを使いたい場合は、gemini-api を使いましょう。OpenAI CLI と同じパターンを Google に向けたものです。

Gemini API CLI のインストール方法

README に記載されている 4 つの方法から 1 つを選んでください。

macOS および Linux：

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

Windows（PowerShell）：

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

Go：

go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

ビルド済みバイナリ： GitHub Releases からお使いのプラットフォーム用のアーカイブをダウンロードし、checksums.txt と照合して、gemini-api を PATH に配置します。私たちは Darwin_arm64 アーカイブを使用しました。shasum -a 256 -c checksums.txt --ignore-missing は OK と表示されました。

Google は、マイナーバージョン間で破壊的な変更が入る可能性があると警告しているため、CI ではリリースを固定してください。ドキュメントでは、インストールスクリプトの bash の前に GEMINI_VERSION=<release-tag> を置く方法が示されています。

インストールを確認します：

gemini-api version
# gemini-api 0.4.5

Gemini API CLI の認証

Google AI Studio でキーを作成し（Gemini API キーを無料で取得する方法はこちらのガイドで解説しています）、それをエクスポートします：

export GEMINI_API_KEY="YOUR_API_KEY"

自分のワークステーションでは、代わりに保存することもできます：

gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami

configure はキーを OS のキーチェーン（macOS Keychain、Linux Secret Service、Windows Credential Manager）に保存します。代わりに ~/.config/gemini-api/config.yaml に保持するには、グローバルフラグ --no-keyring を追加します。whoami は、どの認証情報が有効で、どこから来たのかを表示します。

キーが設定されていない場合、gemini-api --help はエージェント自身に向けた行を表示します。API キーは「ユーザーが Google AI Studio で手動で作成する必要があります。停止して、ユーザーに作成を依頼してください」。エージェントは自分でキーを設定するのではなく、あなたに尋ねてきます。

--dry-run で任意の呼び出しをプレビューする

--dry-run はフラグを検証し、認証情報を伏せた状態でリクエストを表示します。ネットワーク呼び出しもキーチェーンの読み取りも行いません。キーを設定する前でも動作するため、ここでのすべての例はこの方法で確認しました。

以下は、バックグラウンドの Deep Research ジョブの実際のドライランです：

すべてのコマンドは https://generativelanguage.googleapis.com/v1beta/interactions に POST します。-o json を追加すると、リクエストごとに 1 つの JSON オブジェクトが stdout に出力され、エージェントはトークンを使う前にそれを解析できます。

エージェントが実行する Gemini API CLI コマンド

画像の生成と編集

gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg
gemini-api image "Add a winter scarf" -i ./assets/mascot.jpg --out ./assets/mascot-winter.jpg

メディアコマンドはファイルを書き込み、そのパスだけを出力するので、エージェントは $(...) でそれを取得し、構築を続けられます。image は --aspect-ratio と --image-size（512、1K、2K、4K）も受け付けます。デフォルトモデルは Nano Banana 2.1 です。その得意分野については、Nano Banana 2.1 API ガイドをご覧ください。

動画、音声、音楽の生成

gemini-api video "A slow camera move through a sunlit workshop" --resolution 1080p --out ./assets/
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api music "Warm ambient music for a product walkthrough" --out ./assets/

動画はより時間がかかるため、video が代わりにポーリングします。--async を使うとオペレーションハンドルをすぐに取得でき、--resume <id> で後からポーリングを再開できます。--resolution のデフォルトは 720p です。

PDF、画像、YouTube URL の分析

gemini-api analyze -i product-brief.pdf "What should we build first, and why?" > plan.md
gemini-api analyze -i before.png -i after.png "Summarize the visual design changes"

-i/--input は繰り返し指定でき、ローカルパス、files/<id> URI、または YouTube URL を受け付けます。インライン入力は生データで約 14 MB が上限です。より大きなファイルの場合は、一度アップロードして URI を再利用します：

FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze -i "$FILE_URI" "List the key action items with timestamps"

アップロードされたファイルは 48 時間後に削除されます。

音声と動画の文字起こし

gemini-api transcribe -i interview.mp4 --format srt --out interview.srt

--format は md（デフォルト）、text、json、srt を受け付けます。--no-speakers または --no-timestamps を追加すると、出力からそれぞれを削除できます。

バックグラウンドで Deep Research を実行する

ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$ID" --stream=false --output-format json

--background はストリームを開いたままにする代わりに、インタラクション ID をすぐに返します。エージェントは ID を保存し、別の作業を行い、agent status で後から確認します。agent cancel で実行を停止できます。0.4.5 のヘルプには、マネージドエージェントとして deep-research-max-preview-04-2026 と antigravity-preview-05-2026 も記載されています。

gemini-api をエージェントにとって安全にするフラグ

エージェントの指示に含める価値のあるグローバルフラグを以下に示します。すべて gemini-api --help-global からのものです：

• --agent-mode（または GEMINI_CLI_AGENT_MODE=1）：stderr に構造化 JSON エラー、stdout にコンパクトな TOON 出力。
• -o, --output-format：pretty、json、yaml、table、toon。
• -q, --jq：出力をインラインでフィルタリングします。例えば --jq '.id'。
• --no-interactive：プロンプトや TUI フォームを表示しません。ヘッドレスエージェントに必要です。
• --usage：コマンドツリー全体を機械可読な KDL で出力。
• --schema（コマンドごと）：--body ペイロード用の JSON Schema。

終了コードは、テキストを解析することなくエージェントに何が問題だったかを伝えます：0 は成功、1 はランタイムまたは API の失敗、2 は使用法または検証エラー、3 は認証。1 つ注意点があります。ストリーミングコマンド（generate、agent run）は、-o json や --jq で単一の解析可能な結果を得るために、--stream=false が必要です。

コーディングエージェントに Gemini API CLI を渡す

Google の README には、AGENTS.md、CLAUDE.md、.cursorrules に貼り付けるブロックが用意されています。簡略版：

You have access to gemini-api through the shell.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run.
3. For JSON output or --jq on streaming commands, pass --stream=false --output-format json.
4. Capture returned file paths and interaction IDs to continue multi-step tasks.

GEMINI_API_KEY がエージェントのサブプロセス環境に確実に届くようにしてください。あとは通常どおりプロンプトを入力します：「ランディングページを作成し、マスコット画像と 20 秒のナレーションに Gemini を使い、競合製品について Deep Research の実行を開始して」。エージェントがコマンドを選びます。

できないこと：リアルタイムの音声や動画。WebSocket のサポートがないため、Live API には依然として GenAI SDK が必要です。

構築した API を Apidog CLI でテストする

gemini-api はエージェントに Gemini のモデルを提供します。しかし、あなた自身の API については何も知りません。アプリが Gemini をラップする /summarize や /thumbnail エンドポイント、その環境、リリースが壊れていないことを証明するアサーションなどです。それが Apidog CLI の役割であり、同じエージェントが両方を実行できます。

一度セットアップします：

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

そしてエージェントに 1 つのプロンプトを与えます：

Use gemini-api to dry-run an analyze call on ./docs/sample-invoice.pdf, then run it for real.
Import ./openapi.yaml into Apidog project <id>, create a test case for POST /v1/invoices/extract
that uploads the same PDF and asserts a 200 and a non-empty "total" field, run it against the
staging environment, and summarize any failures.

エージェントは gemini-api で Gemini の回答を確認し、次にペイロードを書く前に Apidog スキーマを読み、それを検証し、ケースを作成して実行します：

apidog import --project <id> --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json

apidog test-case create --help は 1 つの落とし穴を指摘しています。ケースには有効な categoryId が必要なので、まず apidog test-case category --project <id> でそれらを一覧表示してください。-r cli,json を -r junit に置き換えれば、同じ行が CI で実行されます。Claude Code をエージェントとして使っている場合は、Claude Code での Apidog CLI から始めてください。Apidog の Free プランは最大 4 ユーザーまで対応しています。

FAQ

Gemini API CLI は無料ですか？ CLI 自体は無料で、Apache 2.0 の下でオープンソースです。すべての呼び出しは、通常の Gemini API の料金に従ってあなたの API キーに課金されます。無料枠でカバーされる内容については、Gemini API 無料枠ガイドをご覧ください。

gemini-api は Gemini CLI と同じですか？ いいえ。Gemini CLI は対話型のコーディングエージェントです。gemini-api は、他のエージェント、スクリプト、CI ジョブが Gemini モデルやマネージドエージェントにアクセスするために呼び出す、ステートレスなツールです。

API キーなしでコマンドをテストできますか？ はい。--dry-run はコマンドを検証し、ネットワーク呼び出しもキーチェーンの読み取りも行わずに、正確なリクエストを表示します。この記事のすべての例は、0.4.5 でこの方法で確認しました。

14 MB を超えるファイルはどう扱えばよいですか？ gemini-api files upload <file> --wait を実行し、返された files/<id> を保持して、analyze、transcribe、generate、image、video、agent run の -i に渡します。アップロードは 48 時間後に失効します。

バージョンを固定すべきですか？ はい、CI では固定してください。Google は、CLI がベータ版の間はマイナーバージョン間で破壊的な変更が起こり得ると述べています。