google-gemini/gemini-skills

gemini-api-cli

Call the Gemini API from the shell with gemini-api.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/google-gemini/gemini-skills --skill gemini-api-cli

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

The gemini-api CLI exposes every Gemini API resource as a shell subcommand. Compared to curl: media and transcription commands decode output to disk and print only the file path, -i attaches local files or files/<id> URIs, --jq extracts fields in-process (raw strings by default, no external jq), --dry-run previews redacted HTTP requests offline, and list endpoints auto-paginate with --all (cap pages with --max-pages N; --page-size sets server page size).

CLI vs SDK

CLI for shell work, SDK for application code. Use gemini-api from terminals, scripts, and CI jobs to generate media files, analyze local PDFs or recordings, run Deep Research, and manage agent sandboxes (gemini-api is a stateless Gemini API client, distinct from the interactive @google/gemini-cli coding agent). Use the Google GenAI SDKs (gemini-api-dev, gemini-live-api-dev) when calls live inside application source or need bidirectional Live API WebSockets.

Install and auth

sh
# macOS / Linux (set GEMINI_VERSION=<tag> to pin a release)
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

Credentials resolve in order (first match wins): --api-key / --access-token flags, GEMINI_API_KEY / GEMINI_ACCESS_TOKEN env vars, the OS keychain, then ~/.config/gemini-api/config.yaml.

  • Env var (agents and CI): export GEMINI_API_KEY="..."
  • Workstation key: gemini-api configure --api-key "..." saves to the OS keychain. Pass --no-keyring or GEMINI_NO_KEYRING=1 on headless Linux to use config.yaml; gemini-api auth logout clears stored keys.
  • Active auth check: gemini-api whoami (add -o json for JSON) prints masked credentials and the winning source.
The #1 auth trap: an exported GEMINI_API_KEY overrides credentials stored in the keychain or config.yaml, billing whichever project that env var belongs to. Check gemini-api whoami to see which source won, or run env -u GEMINI_API_KEY gemini-api ... to ignore the env var.

Command structure

text
gemini-api <intent> [prompt] [flags]          # task commands with model and modality presets
gemini-api <resource> <action> [flags]        # REST resource groups

Run gemini-api --help to list commands, or <subcommand> --help for flags and examples (--usage dumps a 45 KB KDL spec, so stick to --help to save context).

CommandKey flags / actionsDefault model & behavior
generate [prompt]-m, -i, --stdin, --system, --previous-interaction-id, --stream=false, --bodygemini-4-hydrogen; streams text deltas to stdout
image [prompt]-m, -i, --aspect-ratio, --image-size (512..4K), --previous-interaction-id, --out, --bodygemini-nano-banana-2.1; writes image, prints path
tts [text]-m, -f, --stdin, -v/--voice (default Kore), --multi-speaker, --language, --outgemini-3.8-flash-tts; writes 24 kHz WAV, prints path (unstored)
music [prompt]-m, -f, --stdin, --out, --bodylyria-3.5; writes audio track, prints path
video [prompt]-m, -i, --aspect-ratio, --resolution (360p..4k), --previous-interaction-id, --async, --resume, --out, --bodypass -m gemini-omni-1.2-flash (≤ v0.4.5 preset defaults to gemini-omni-1.1-flash); polls until done, writes MP4, prints path (upscale via --body)
analyze [question]-i (required, repeatable), --stdin, --system, -mgemini-4-hydrogen; answers over PDFs, media, CSV/text, YouTube URLs (unstored)
transcribe-m, -i (required, repeatable), --format (md, text, json, srt), --no-speakers, --no-timestamps, --outgemini-3.5-transcribe (audio; 30m speaker/timestamp cap) or gemini-4-hydrogen (video); writes --out (or ./transcript-*), prints path (unstored)
agentrun, status, cancel, delete-interaction; create, list, get, deleteRuns models or managed agents; manages custom agent definitions
filesupload [--wait], list, get, generated-files-list, register, deleteUploads reusable files/<id> URIs (48h TTL; up to 2 GB, 50 MB PDFs)
models(bare), list [--all], get <id>Bare models prints an offline catalog; list and get query the live API
environmentscreate, list, get, delete, files (list, upload, download), connect, poll, serveRemote sandboxes and workspace snapshots (credentials, webhooks, triggers for agent infra)

Model selection: use gemini-4-hydrogen (default), gemini-4-carbon (hard reasoning and coding), or gemini-3.5-flash-lite (high throughput); for images, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, or gemini-3-pro-image; for video, gemini-omni-1.2-flash. Avoid deprecated gemini-2.5-*, gemini-2.0-*, and gemini-1.5-* models.

Global flags

FlagPurpose
-o, --output-formatpretty (default), json, toon, yaml, table
-q, --jqFilter JSON output with a built-in jq expression (--raw-output is true by default)
--agent-modeCompact TOON on stdout and structured JSON errors on stderr
--no-interactiveDisable prompts, TUI forms, and explore
--dry-runValidate inputs and preview redacted HTTP requests offline (human preview on stderr; -o json or --jq writes JSON to stdout)
-d, --debugLog HTTP request and response details to stderr

Exit codes: 0 ok, 1 runtime or API error (video polling, image/music, tts, transcribe, and analyze also exit 1 on failed/incomplete runs; generate, agent run, and agent status exit 0 and report state in .status), 2 usage or validation error, 3 auth error. See gemini-api --help-global for --server-url and auth flags; pagination flags (--all/-a, --max-pages, --page-size, --page-token) live on <resource> list --help.

Output

Media (image, tts, music, video) and transcribe write files locally and print only the file path on stdout (--out on media commands rewrites the file extension to match the returned MIME type, e.g. .png for default image unless --body '{"response_format": {"mime_type": "image/jpeg"}}' is passed). Adding -o json still writes the file and prints metadata: {kind, path, size_bytes, mime_type, response_id, status} on image/music/video, {model, path, mime_type, size_bytes, sample_rate, channels} on tts, and {model, format, results: [{input, path, size_bytes, model, mime_type}]} on transcribe.

Streaming and JSON shape: generate and agent run stream plain reply text by default, so -o json alone emits {"data": ...} NDJSON SSE events. Pass --stream=false -o json for one JSON object {id, status, steps, usage} (bare --stream=false prints aligned key: value metadata; --background on agent run disables streaming, and --jq disables streaming unless -o or GEMINI_OUTPUT_FORMAT is set, so omit -o json or add --stream=false when filtering a full response with --jq). Reply text lives under .steps[] model_output (see agent status below) rather than .candidates[]. On paginated list commands, --jq runs per page envelope (.models[]?.name, .agents[]?.id).

Input

  • -i / --input attaches media and documents on generate, image, video, analyze, transcribe, and agent run (repeatable). Accepts local paths up to ~14 MB (20 MB base64 cap), files/<id> URIs, or YouTube URLs (not supported on transcribe). Upload larger or reused files once with gemini-api files upload <path> --wait.
  • -f / --file reads prompt text from a file on tts and music. Piped text needs `--stdin`: when piping plain text into generate, image, music, or video, pass --stdin or piped input gets parsed as a JSON --body; analyze and tts ignore piped stdin unless --stdin is set (agent run has no --stdin, so piped stdin is always JSON --body).
  • --body passes raw Gemini API JSON inline, from @file.json, or via @- (merges with flags; exits 2 on duplicate keys). Use it for response_format schemas, tools (google_search, code_execution, url_context, function declarations), generation_config, environment, or store.
  • Don't dump `--schema` raw: it prints ~92 KB of minified JSON and exits before --jq runs. Pipe it to jq:
sh
  gemini-api generate --schema | jq '."$defs".ModelInteraction.properties | keys'

Media, analysis, and transcription

sh
HERO=$(gemini-api image "Isometric cloud database icon" --aspect-ratio 16:9 --image-size 2K \
  --body '{"response_format": {"mime_type": "image/jpeg"}}' --out ./hero.jpg)
gemini-api image "Add warm sunset lighting" -i "$HERO" \
  --body '{"response_format": {"mime_type": "image/jpeg"}}' --out ./hero-sunset.jpg

gemini-api tts "Alice: Ready to ship? Bob: Checks are green." \
  --multi-speaker "Alice=Kore,Bob=Puck" --out ./dialogue.wav

VID_ID=$(gemini-api video "Aerial coastal cliffs at sunrise" -m gemini-omni-1.2-flash --aspect-ratio 16:9 --resolution 1080p --async)
gemini-api video --resume "$VID_ID" --out ./cliffs.mp4

FILE_URI=$(gemini-api files upload ./call.mp4 --wait)   # prints files/<id>
gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format srt --out ./call.srt

Managed agents and sandboxes

  • deep-research-preview-04-2026 and deep-research-max-preview-04-2026: run with --background and poll agent status.
  • antigravity-preview-09-2026 (Linux sandbox with Bash, Python, Node, file ops, and web search): pass "environment": "remote" (new sandbox), "environment": "<env_id>" (existing sandbox), or "environment": {"type": "remote", ...} in --body (top-level environment_id is output-only and exits 2).

ID boundary: agent status, agent cancel, and agent delete-interaction take a run ID (v1_...). agent create, agent get, agent list, and agent delete manage custom agents only (built-in agent IDs are listed in gemini-api agent run --help and live gemini-api models list, not the offline gemini-api models catalog; cap agent list and environments list with --page-size 10).

sh
RUN_ID=$(gemini-api agent run "Compare WebRTC SFU architectures with primary sources." \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$RUN_ID" --jq '.status'   # queued | in_progress | requires_action | requires_continuation | completed | failed | cancelled | incomplete | budget_exceeded (exits 0)
gemini-api agent status "$RUN_ID" \
  --jq '[.steps[]? | select(.type=="model_output") | .content[]? | select(.type=="text") | .text] | join("")'

ENV_ID=$(gemini-api agent run "Benchmark radix sort vs timsort in Python and write results.csv." \
  --agent antigravity-preview-09-2026 --body '{"environment": "remote"}' --jq '.environment_id')
gemini-api environments files list -e "$ENV_ID" -r
gemini-api environments files download "$ENV_ID" results.csv --out ./results.csv

gemini-api agent create --id code-reviewer --base-agent antigravity-preview-09-2026 \
  --system-instruction "Review diffs for race conditions and auth bugs."

Multi-turn and structured output

Calls store state server-side by default (store is true), so multi-turn chains only need --previous-interaction-id (system_instruction, tools, and generation_config apply per turn; setting store to false disables previous_interaction_id and background):

sh
TURN1=$(gemini-api generate "Propose 2 indexing strategies for time-series logs." --jq '.id')
gemini-api generate "Compare them for write-heavy workloads." --previous-interaction-id "$TURN1"

Combine --stdin with --body for schema-constrained JSON output:

sh
cat build.log | gemini-api generate "Extract unique compiler errors." --stdin --body '{
  "response_format": {
    "type": "text", "mime_type": "application/json",
    "schema": {"type": "object", "properties": {"errors": {"type": "array", "items": {"type": "string"}}}, "required": ["errors"]}
  },
  "store": false
}'

Full CLI reference: aistudio.google.com/docs/cli.md; docs index: llms.txt.

du même dépôt

Autres Skills

Tous les Skills
google-gemini
Officiel

gemini-api-dev

Use this skill when writing code that calls the Gemini API for text generation, multi-turn chat, multimodal understanding, image generation, video generation, speech generation (TTS), voice design, voice replication, streaming responses, background research tasks, function calling, structured output, calibrated decisions (yes/no, choice, rubric scoring), or migrating from the old generateContent API. Covers SDK usage and best practices for Gemini models and agents in Python and TypeScript.

Installations / 1h
4
GitHub Stars
4,5 k
Mis à jour
19 nov.
google-gemini
Officiel

gemini-live-api-dev

Use this skill when building real-time, bidirectional streaming applications with the Gemini Live API, or migrating legacy Live models (2.0/2.5/3.1) to Gemini 3.8 Live. Covers WebSocket-based audio/video/text streaming, voice activity detection (VAD), background reasoning (extended thinking), asynchronous function calling, session management, ephemeral tokens, live transcription, and live translation. SDKs covered - google-genai (Python), @google/genai (JavaScript/TypeScript).

Installations / 1h
2
GitHub Stars
4,5 k
Mis à jour
19 nov.
google-gemini
Officiel

gemini-omni-flash-api

Use this skill for generative video editing, text-to-video, image- and video-referenced video generation, first-frame-to-video, first-and-last-frame transitions, and video extensions using Gemini Omni 1.2 Flash (gemini-omni-1.2-flash) via the official google-genai SDK. Includes workflows for pre-processing/optimizing high-resolution or long source videos with ffmpeg, stripping audio for full sound regeneration, and handling turn-by-turn video editing and parallel execution.

Installations / 1h
3
GitHub Stars
4,5 k
Mis à jour
12 nov.