gemini-api CLI: give Claude Code or Codex image, voice and video generation in 5 minutes

Your coding agent can write a landing page, but it can't draw the mascot or record the welcome voiceover. Google's gemini-api CLI fixes that for any agent with a shell. Install one binary, set an API key, and Claude Code, Codex or Antigravity can generate images, speech, music and video, or analyze a PDF, mid-task. As of Oct 22, 2026, the latest release was v0.4.3 (Oct 19).

Not to be confused with Gemini CLI, Google's own coding agent. gemini-api is a tool your agent calls.

What it can do

From the README's command table (default models in brackets):

Want the new Gemini 4 Argon instead? Run gemini-api models list to see live model IDs and pass one with -m. Check Argon's pricing first.

Step 1: install

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

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

You can also download prebuilt binaries from GitHub Releases. As with any curl | bash installer, open the script first if you want to see what it does.

Step 2: add your API key

Create a key in Google AI Studio, then:

export GEMINI_API_KEY="YOUR_API_KEY"

To keep it in your OS keychain instead of your shell profile:

gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami   # shows which credential is active

Never paste the key into a prompt or commit it. Our vibe coding security checklist covers secrets.

Step 3: test without spending anything

gemini-api generate "Hello from my agent" --dry-run
gemini-api generate "Hello from my agent"

--dry-run validates the command and prints the HTTP request with credentials redacted. It makes no network call.

Step 4: tell your agent it exists

Paste Google's suggested block into AGENTS.md, CLAUDE.md or .cursorrules:

You have access to gemini-api through the shell.
Use it to call Gemini models, generate or edit media, analyze files, or launch managed agents.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run (or --dry-run --output-format json).
3. For discrete JSON output or --jq filtering on streaming/background commands (generate, agent run, agent status), pass --stream=false --output-format json.
4. Capture returned file paths (from media commands) and interaction IDs (from agent/model runs) to continue multi-step tasks.

New to these files? See what AGENTS.md is and how to write one.

Step 5: use it

Prompt your agent as usual:

Build a landing page for this app. Use Gemini to create a mascot image and a welcome voiceover. Incorporate them into the page.

Behind the scenes, the agent runs commands like:

gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api analyze -i ./docs/spec.pdf "List the three main requirements"

Media commands write the file and print only its path, so the agent can use it right away.

Settings worth knowing

• --agent-mode (or GEMINI_CLI_AGENT_MODE=1): structured JSON errors and compact output, built for agents.
• --no-interactive: disables prompts that could hang an agent.
• Exit codes: 0 success, 1 API/runtime failure, 2 bad usage, 3 auth failure. These are useful in hooks and CI.
• Files API uploads are kept for 48 hours.

Costs and safety

• Every real call bills your Gemini API key. Video and managed agents can add up. Set a budget alert in Google Cloud, and keep your agent's permissions on "ask" while you learn. See running coding agents safely.
• Managed agents run in the background. The CLI returns an interaction ID; use gemini-api agent status and agent cancel to keep track.
• Check what you generate before shipping, especially images or voices that look or sound like real people or brands.