Google Releases Gemini API CLI: Bringing Image, Video, Voiceover, and Research Capabilities Directly to Existing Agents

Google has released Gemini API CLI (command gemini-api), a command-line tool allowing existing Agents like Codex and Claude Code to invoke Google's multimodal models and managed Agents directly from the terminal. It is currently in preview, and interfaces remain subject to change.

It packages several operational workflows into a single utility:

• Cross-platform installation: Ships as a single binary across macOS, Linux, and Windows, eliminating the need to install Node.js, Python, or configure complex runtime environments.
• Asset generation and multimodal understanding: A unified CLI covering text inference, image generation and editing, multi-speaker voice synthesis, background music generation, video creation, as well as long document/audio/video understanding and subtitle transcription.
• Direct file persistence into projects: Generated images, videos, and audio are written directly to local disk, with the terminal outputting only file paths by default so Agents can seamlessly continue downstream work.
• Offline usage inspection and request validation: Agents can inspect commands and parameters offline, using --dry-run to validate request payloads before dispatching them over the wire.
• Delegation to background research agents: Supports non-blocking invocation of Gemini managed backend Agents (such as Deep Research), returning an Interaction ID immediately so host Agents can poll status and retrieve structured results at will.
• Host-managed session resumption: The CLI does not maintain local conversation history; host Agents retain context or resume interactions using server-side interaction IDs.

Keep Your Existing Host Agent While Gemini Supplies On-Demand Capabilities

When asking Codex or Claude Code to build a landing page, it still determines the page structure, decides what assets are required, executes terminal commands, and integrates the resulting files into the markup. The Agent orchestrating the overall task is referred to as the "host Agent." Integrating model capabilities into application backends typically relies on SDKs—language-specific client libraries. Conversely, enabling an Agent to generate media assets ad hoc from a terminal can be achieved directly via a CLI.

The stack features a shared foundation accessible via two parallel entry points:

• Gemini API & Managed Agents (Foundation): A unified suite of multimodal models and server endpoints spanning reasoning (Gemini 3.8 Flash), image generation (Gemini Nano Banana 2.1), video generation (Gemini Omni 1.1 Flash), music synthesis (Lyria 3.5), speech synthesis (Gemini 3.8 Flash TTS), and managed research services (Deep Research).
• Google Gen AI SDKs (Code Integration): Typed client libraries across Python, TypeScript, Go, and Java tailored for production backends and microservice codebases.
• Gemini API CLI (Command-Line Entry Point): The standalone gemini-api binary tailored for terminal workflows and Coding Agent shell execution loops, communicating directly with the API and persisting media files to disk.

Ensure you use the complete name Gemini API CLI and binary gemini-api, avoiding confusion with Gemini CLI.

In typical autonomous coding workflows, responsibilities are divided as follows:

• Host Agent (e.g., Codex, Claude Code, Google Antigravity, Cursor, OpenClaw): Plans build tasks (such as writing web pages), decides when assets are needed, runs terminal commands, and incorporates generated assets.
• Gemini API CLI (gemini-api): Receives arguments in the shell, calls the API, writes generated media directly to disk, and prints file paths or interaction IDs to standard output.
• Gemini Models & Platform Services: Processes incoming requests to perform image synthesis, audio rendering, cross-modal reasoning, and deep background research.

Eliminating Custom Scripts by Delivering Files Straight to the Next Step

When a Coding Agent calls multimodal APIs through generic HTTP requests, image or audio data may be printed to stdout as raw Base64 text. If that happens, the host Agent reads the encoded media as terminal output, consuming its context window.

While developers could instruct an Agent to write ad-hoc scripts to query endpoints and persist payloads, that requires writing custom boilerplate for response parsing, decoding, and file I/O—frequently running into dependency or formatting issues. gemini-api standardizes this behavior: when generating images, audio, or video, the CLI automatically writes the file to the designated disk path and prints only the local path to stdout by default. This eliminates boilerplate script authoring while preventing media encodings from flooding the Agent's context.

gemini-api image "Isometric icon of a distributed database" --out ./assets/

In practice, when generating a hero image for a landing page, the host Agent executes a single command. The CLI writes the image to disk and returns its path to stdout; the host Agent then references that path in an <img> tag and continues building the layout. For structured data, passing --output-format json alongside the built-in --jq flag allows direct extraction of specific fields.

Once gemini-api is installed and configured, send the complete task below in the chat of your Codex, Claude Code, or Antigravity Agent:

Build a landing page for this app. Use Gemini to create a mascot image and a welcome voiceover, and launch a managed research agent to investigate competing products. Incorporate the assets and findings into the page.

You define the objective, and the host Agent decides which commands to run. Once generated, assets are wired into the page, and the findings from competitor research are integrated when ready.

From Image Generation to Voiceover, Subtitling, and Background Research

Before invoking the API, complete installation and credential setup; offline usage queries and dry-runs do not initiate network calls. Except for Windows installation commands, the following examples use Bash syntax compatible with macOS, Linux, or Windows environments running Bash (such as WSL). Replace sample paths with your actual project filenames.

1. Image Generation and Secondary Editing

gemini-api image defaults to the gemini-nano-banana-2.1 model. The --out flag specifies the output file or destination directory; if pointed to a directory, the CLI automatically appends the appropriate extension based on the MIME type returned by the API (such as .jpg).

gemini-api image "Isometric icon of a distributed database" --out ./assets/database-icon.jpg

After execution, standard output prints only the absolute or relative file path (such as ./assets/database-icon.jpg).

To make secondary edits on an existing image, the official README provides a complete two-step example generating and editing a robot mascot (passing the source image path via -i or --input):

# Step 1: Generate initial robot mascot image and capture output path
MASCOT_PATH=$(gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg)

# Step 2: Pass source image using -i for editing
gemini-api image "Add a winter scarf and snowy background" -i "$MASCOT_PATH" --out ./assets/mascot-winter.jpg

2. Video Generation

gemini-api video defaults to the gemini-omni-1.1-flash model, turning text prompts into dynamic footage via conversational video generation capabilities.

gemini-api video "A slow camera move through a sunlit workshop" --out ./assets/workshop.mp4

3. Multi-Speaker Voice Synthesis and Background Music

For scenarios requiring voiceovers or background audio, gemini-api tts provides multi-speaker dialogue synthesis powered by Gemini 3.8 Flash TTS, while gemini-api music utilizes the Lyria 3.5 music generation model.

gemini-api tts "Alice: Deployment succeeded! Bob: Let's ship it." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./assets/dialogue.wav

In this command, Alice and Bob are dialogue characters, while Kore and Puck are the assigned voices matching the character names on the left; the synthesized dialogue is saved as a single audio file.

gemini-api music "Lo-fi ambient background track for a focus app" --out ./assets/focus-bg.mp3

4. Multimodal Document Analysis and Speech Transcription

gemini-api analyze and gemini-api transcribe inspect existing media assets, both defaulting to gemini-3.8-flash. In addition to local PDF, image, audio, video, and text files, gemini-api analyze can directly accept YouTube URLs.

gemini-api analyze -i architecture.pdf "Summarize the key bottlenecks"

Analyses of this type return text to the terminal by default for the host Agent to consume; to persist findings, redirect output to a file like > plan.md as shown in the README.

After modifying a page, the host Agent can also pass before-and-after screenshots together to Gemini to summarize visual design changes. The --input flag can be repeated for multiple files; replace before.png and after.png with your actual screenshot paths:

gemini-api analyze --input before.png --input after.png "Summarize the visual design changes"

gemini-api transcribe -i earnings_call.mp3 --format srt --out earnings_call.srt

In the transcription example, the official documentation shows the generated earnings_call.srt subtitle sample:

1
00:00:03,000 --> 00:00:07,000
Speaker 1: Welcome to the third quarter earnings call.

2
00:00:16,000 --> 00:00:20,000
Speaker 1: Revenue grew 20% year-over-year.

Each subtitle entry consists of a sequence number, start and end timestamps, and the subtitle text. Matching the timecodes reveals where each statement occurs in the recording.

For larger media files (raw files above ~14 MB, or ~20 MB after Base64 encoding), the README recommends staging via the Files API: run files upload --wait to upload large files to managed storage (retained for 48 hours), then reference the returned URI:

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

5. Resuming Long-Running Tasks with Managed Background Agents (Deep Research)

For complex tasks requiring multi-step web searches and cross-verification, the CLI offers a non-blocking background execution mode:

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

echo "Started interaction: $INTERACTION_ID"

Running these commands does not trigger push notifications upon completion; the host Agent must persist the returned interaction ID (INTERACTION_ID). While the task executes, the host Agent can proceed with other work and periodically check progress using agent status, retrieving structured results once complete:

gemini-api agent status "$INTERACTION_ID" --stream=false --output-format json

Letting the Tool Explain Itself When an Agent Needs Guidance

Inside Google Antigravity, developers can invoke gemini-api directly through the workspace shell, with official native integration planned. The official team also used Antigravity 2.0 to call gemini-api video and create promotional video clips for this launch; the image below shows the workspace commands and generated-file preview.

Instructing Agents When to Use It in Projects

To enable Claude Code, Codex, Cursor, Antigravity, or custom Agents to call gemini-api smoothly, add the following instruction block to your project root configuration (such as 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.

Parameter Discovery, Dry-Runs, and Output Retrieval

1. Self-Describing Interfaces and Model Discovery: gemini-api --help lists commands and arguments, while --usage outputs a machine-readable command tree. When an Agent wants to generate an image but cannot recall the active model name, it can run gemini-api models to view the built-in offline catalog, or gemini-api models list --all to query all live models available to the current API key, specifying models via -m. For commands accepting request bodies (like image or agent run), running gemini-api <command> --schema exports the built-in request schema to help construct valid payloads.

2. Offline Validation (Dry-Run): Appending --dry-run to any command validates arguments locally and prints a sanitized HTTP request preview without making network calls or reading system keychains. Note that --dry-run verifies only syntax and payload structure; it does not verify that the remote API key is active, that the account has permission for the specified model, that quota remains available, or that generation quality meets expectations.

3. Output Contracts and Agent Mode: Enabling --agent-mode (or setting GEMINI_CLI_AGENT_MODE=1) causes the CLI to emit structured JSON error envelopes to stderr upon failure while compacting default stdout output. It also adheres to strict exit codes (0 for success, 1 for runtime/API errors, 2 for invalid arguments, 3 for authentication/authorization failures).

4. From Simple Flags to Custom Payloads (--schema to --body): Short flags cover high-frequency everyday needs, but when fine-tuning underlying generation parameters is required, use --body to inject a complete JSON payload. For instance, generating an asset with a specific aspect ratio (16:9) and high resolution (2K):

   View hero-image.json payload

   cat > hero-image.json <<'JSON'
   {
     "model": "gemini-nano-banana-2.1",
     "input": "A friendly robot mascot in a sunlit workshop, composed on the right with uncluttered space on the left for a landing page headline. No text or watermark.",
     "response_format": {
       "type": "image",
       "aspect_ratio": "16:9",
       "image_size": "2K"
     },
     "store": false,
     "stream": false
   }
   JSON
   

   # Validate payload offline
   gemini-api image --body @hero-image.json --out ./assets/hero.jpg --dry-run --output-format json
   
   # Execute generation
   gemini-api image --body @hero-image.json --out ./assets/hero.jpg --output-format json
   

   Here, --out designates where files are saved, while response_format dictates image specifications; --output-format json instructs the CLI to return structured metadata including the file path, rather than a single-line path string.

5. Stateless Client Design and Multi-Turn Session Chaining: The CLI stores no session history locally, but the backend is not stateless. The lifecycle of server-side interactions is managed by the API, allowing host Agents to capture the interaction ID from turn 1 and pass it explicitly via previous_interaction_id inside --body:

   # Turn 1: Run inference and capture server-returned interaction ID
   TURN1_ID=$(gemini-api generate "Propose 3 database indexing strategies for a time-series log table." \
     --stream=false --jq '.id')
   
   # Turn 2: Reference previous_interaction_id to continue conversation
   gemini-api agent run "Compare strategy #2 and #3 for write-heavy workloads." \
     --body "{\"previous_interaction_id\": \"$TURN1_ID\"}" \
     --stream=false
   

Installation and Getting Started

1. Installation Methods

Official installation is supported via automated scripts or Go source builds:

• macOS and Linux (Bash):

  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 Source Installation (requires Go 1.26.10 or higher to compile current main):

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

2. Credential Configuration and Offline Verification

After installation, ensure the gemini-api binary is accessible in your system PATH and that subshells spawned by host Agents inherit the same environment. Obtain an API key from Google AI Studio and configure the CLI.

The CLI supports multiple credential storage mechanisms (saving to the OS keychain or ~/.config/gemini-api/config.yaml depending on environment and parameters):

# Method A: Set environment variable (ideal for CI/CD or Agent subshells)
export GEMINI_API_KEY="your-api-key"

# Method B: Persist to storage (writes to OS keychain or local config file)
gemini-api configure --api-key "your-api-key"

# Method C: Launch interactive terminal setup wizard
gemini-api configure

Once configured, verify the environment offline:

# View active configuration and credential source (without verifying remote validity)
gemini-api whoami

# Validate request construction offline (no network request made)
gemini-api generate "Hello from my agent" --dry-run

3. Quota and Pricing Details

The official documentation does not specify a unified CLI subscription plan. Actual access, quotas, and billing are governed entirely by the account associated with the supplied GEMINI_API_KEY and the specific models called (such as Gemini 3.8 Flash, Nano Banana 2.1, Lyria 3.5, or Deep Research) per official pricing schedules. Third-party Agent subscriptions (such as Claude Pro, Cursor, or Codex) should not be assumed to include Gemini API quota; usage is billed according to standard Gemini API terms.

gemini-api is currently an experimental preview (v0.4.x), and interfaces or flags may incur breaking changes. When integrating into automated pipelines or production environments, pin specific release versions; remember that --dry-run checks only local parameter structure, and actual API calls remain necessary to verify behavior across version upgrades.