/gemini-api

name: gemini-api
description: "Call the Gemini API from the shell with Google's `gemini-api` CLI, when that binary is installed — text and reasoning, image generation and editing, text-to-speech, music, video, document/audio/video/YouTube analysis, transcription and captions, file uploads, and managed agents (Deep Research) run in the background. Use when the task needs a Gemini model or a second opinion from one, a generated image/voiceover/soundtrack/clip, an answer out of a PDF or recording, an SRT caption file, or a long-running research agent. Triggers: 'use gemini', 'ask gemini', 'gemini-api', 'generate an image', 'make a voiceover', 'transcribe this', 'analyze this PDF', 'deep research'. Not for writing application code against the Gemini SDK or Vertex AI."
license: Apache-2.0
metadata:
  author: sanjay3290
  version: "1.1"

Gemini API from the shell

`gemini-api` is Google's single-binary CLI for the Gemini Interactions API. Each invocation does one thing and returns either text on stdout or a file path on disk.

Verified command details, output shapes, and gotchas: `references/cli.md`.

Preflight (once per session, before the first call)

`gemini-api whoami` prints the config file, the credential source, and the active defaults. If it reports no API key, stop and ask the user to set one — never guess at a key or edit their config. The persistent form is `gemini-api configure --api-key "..."`, which writes to the OS keychain; `GEMINI_API_KEY` in the environment also works.

If the binary is missing, say so and offer to install it from <https://github.com/google-gemini/gemini-api-cli> (`install.sh`, or `go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest`). Do not pipe an install script into a shell without the user agreeing first, and do not hand-roll `curl` calls against the REST API as a substitute.

The CLI is beta and the Interactions API moves fast. When a flag in this skill is rejected, trust the binary: run `--help` on that command and adapt.

The discovery loop

Never guess a flag. The binary describes itself, offline and without credentials:

| Need | Run | |---|---| | Which command, which flags | `gemini-api <cmd> --help` | | The whole command tree, machine-readable | `gemini-api --usage` (KDL) | | The exact request body schema | `gemini-api <cmd> --schema` | | Validate before spending a call | `gemini-api <cmd> ... --dry-run` | | Every global flag | `gemini-api --help-global` |

`--dry-run` makes no network call and does not read the keychain, but it does read local `--input` files, so it also checks that they exist and that the MIME type is detected.

Pick the command for the task

| Task | Command | Default model | |---|---|---| | Ask a model, stream the reply | `generate` | `gemini-3.8-flash` | | Generate or edit an image | `image` | `gemini-nano-banana-2.1` | | Voiceover, narration, two-speaker dialogue | `tts` | `gemini-3.8-flash-tts` | | Music bed, soundtrack | `music` | `lyria-3.5` | | Video clip, or edit one conversationally | `video` | `gemini-omni-1.1-flash` | | Question about a PDF, image, audio, video, CSV, or YouTube URL | `analyze` | `gemini-3.8-flash` | | Transcript or SRT captions | `transcribe` | `gemini-3.5-transcribe` | | Long-running research or agent task | `agent run --background` | `--agent deep-research-preview-04-2026` | | Reuse a file over several calls, or send >14 MB of media | `files upload --wait` | — | | See what models this key can reach | `models` / `models list --all` | — |

Full request control for anything the short flags do not reach: `agent run --body @req.json`, after `gemini-api agent run --schema`. `--body` is available on `generate`, `image`, `music`, `video`, and `agent run` only.

Output discipline

• **Piped stdin is read as a JSON request body, not as prompt text.** `cat notes.md |

gemini-api generate "summarize"` fails with a parse error. Add `--stdin` to send piped text as the prompt. This is the most common first-run failure.

• **Media commands print the written file path on stdout, nothing else.** Capture it:

`MASCOT=$(gemini-api image "..." --out ./assets/mascot.jpg)`.

• **Progress lines go to stderr, the payload to stdout**, so command substitution gets a

clean value. Do not discard stderr — it carries the real errors.

• **For anything to be parsed, turn streaming off.** `--stream=false -o json` returns one

complete interaction object. While streaming, `-o json` emits the raw NDJSON event stream instead.

• **Pull out one field with `--jq`.** It works without `-o json`, and `--raw-output` (on

by default) prints strings unquoted. The reply text is nested in `steps`, not at the top level:

gemini-api generate "..." --stream=false \
  --jq '[.steps[] | select(.type=="model_output") | .content[].text] | join("")'

Exit codes are meaningful: `0` ok, `1` runtime/API failure, `2` bad usage or validation, `3` auth. Branch on them instead of grepping stderr. `-o json` turns errors into a structured JSON envelope on stderr; `--agent-mode` does the same but also switches default stdout to TOON, so pair it with `-o json` or `--jq`.

Cost and care

Every non-`--dry-run` call spends the user's API quota, and image, music, and video calls are the expensive ones.

• Do not generate paid media speculatively. One image, then ask.
• Default to a cheap model for routine text — `-m gemini-3.1-flash-lite` as of 0.4.5.

Reserve the Pro and frontier models for hard reasoning the user asked for.

• Run media commands with `--dry-run` first when the payload is hand-built.
• Always pass `--out` with an explicit path. Without it, generated files land in the

working directory under an auto-generated name.

• Uploaded files expire after 48 hours. Delete what a workflow no longer needs:

`gemini-api files delete files/<id>`.

Background work

A managed agent run can take many minutes. Start it detached, keep the ID, and do other work:

ID=$(gemini-api agent run "R