CLI de l'API Gemini

La CLI de l'API Gemini (gemini-api) est un client de ligne de commande sans état et sans dépendance, conçu pour les agents IA disposant d'un accès au shell (et utilisable à partir de scripts et de l'intégration continue). Votre agent de codage peut ensuite générer du texte et des contenus multimédias, analyser des fichiers et déléguer des tâches aux agents gérés Gemini. Il fonctionne avec Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes ou n'importe quel environnement de shell.

Chaque fonctionnalité s'exécute en tant que commande shell standard sur l'API Interactions. Exécutez les mêmes commandes à partir d'un sous-processus d'agent, de votre terminal ou d'un pipeline d'intégration continue :

# 1. Install on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# 2. Set your API key
export GEMINI_API_KEY="YOUR_API_KEY"

# 3. Generate media, analyze a file, or launch a background managed agent
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false

Choisir le bon outil Gemini

Utilisez gemini-api lorsqu'un agent ou un script doit appeler Gemini directement depuis le shell sans ajouter de code SDK à votre projet. Utilisez les SDK et la configuration de l'agent de codage lorsque vous intégrez Gemini à une application :

Fonctionnement

Les appels REST bruts et les CLI interactives posent souvent problème aux agents de codage. Les contenus multimédias en Base64 remplissent la fenêtre de contexte, les requêtes interactives bloquent les sous-processus et les données d'entraînement obsolètes provoquent des hallucinations.

Quatre choix de conception permettent à gemini-api de rester fiable pour les agents :

• Recherche de schéma hors connexion : transmettez --usage pour imprimer l'arborescence de commandes (dans KDL) ou --schema pour imprimer le schéma JSON pour les requêtes --body.
• Fichiers sur le disque, chemins d'accès sur stdout : les commandes de contenu multimédia et de transcription écrivent des fichiers sur le disque et n'impriment que le chemin d'accès de sortie, en conservant les données binaires hors contexte.
• Simulations et sortie structurée : --dry-run valide les entrées, masque les identifiants et prévisualise la requête HTTP hors connexion. Transmettez -o json, -o toon ou --jq pour une sortie lisible par machine. Ajoutez --agent-mode pour renvoyer des erreurs JSON structurées sur stderr, et vérifiez les codes de sortie pour gérer les échecs. Les commandes ne s'affichent jamais, sauf si vous transmettez --interactive.
• Sans état par défaut : les commandes ne conservent aucun état local masqué. Enchaînez explicitement les tâches en plusieurs étapes avec --previous-interaction-id, un URI files/<id> importé ou un ID d'interaction en arrière-plan.

Avec -o json, les commandes multimédias écrivent toujours le fichier sur le disque et affichent les métadonnées dans stdout :

{
  "kind": "image",
  "mime_type": "image/jpeg",
  "path": "/path/to/project/assets/db-icon.jpg",
  "response_id": "v1_...",
  "size_bytes": 2914159,
  "status": "completed"
}

Commencer

Installez la CLI, placez gemini-api sur votre PATH, définissez GEMINI_API_KEY et ajoutez des règles d'utilisation à votre agent de codage.

1. Installer le binaire

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

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash

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

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

2. Configurer l'authentification et vérifier

Créez une clé API dans Google AI Studio (voir Clés API). Définissez GEMINI_API_KEY dans votre shell et dans l'environnement de sous-processus de votre agent :

export GEMINI_API_KEY="YOUR_API_KEY"

Sur un poste de travail local, vous pouvez enregistrer la clé dans le trousseau de votre OS (trousseau macOS, Linux Secret Service ou Windows Credential Manager). Transmettez --no-keyring pour stocker la clé dans ~/.config/gemini-api/config.yaml à la place :

# Save to your OS keychain (or run gemini-api configure --interactive)
gemini-api configure --api-key "YOUR_API_KEY"

# Check the active credential source, then preview a request offline
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run

3. donner des instructions à votre agent

Ajoutez cet extrait au fichier AGENTS.md, CLAUDE.md, .cursorrules ou à la requête système de votre projet pour que votre agent de codage sache comment utiliser gemini-api :

## Gemini API CLI (`gemini-api`)

You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.

1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.

Ensuite, envoyez un prompt à votre agent de codage comme d'habitude :

Build a landing page for our developer tool. Use Gemini to generate a hero
illustration and a 15-second welcome voiceover, and start a background Deep
Research agent to compare competing CLI onboarding flows. Wire the assets and
findings into the page.

Commandes

Exécutez gemini-api --help pour lister toutes les commandes ou gemini-api explore pour les parcourir de manière interactive.

Workflows

Chaque commande utilise par défaut un modèle adapté à sa tâche. Transmettez --model (-m) pour choisir un autre modèle. Exécutez gemini-api models pour lister les options disponibles.

Génération et modification d'images

Les agents qui créent des interfaces utilisateur Web ou mobiles peuvent générer des espaces réservés, des icônes et des images héros avec Nano Banana. Transmettez un chemin d'accès généré avec -i pour modifier l'image :

# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path
HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --out ./public/images/hero.jpg)

# Edit the generated image
gemini-api image "Add a winter scarf and soft snowfall outside the window" \
  -i "$HERO_PATH" \
  --out ./public/images/hero-winter.jpg

Transmettez -i plusieurs fois pour combiner des images de référence, comme un personnage et un guide de style.

Synthèse vocale

gemini-api tts synthétise l'audio WAV 24 kHz pour les signaux de l'interface utilisateur, les aperçus d'accessibilité et les tutoriels narrés. La voix par défaut est Kore. Choisissez-en une autre avec --voice. Pour un dialogue à deux locuteurs, étiquetez chaque tour de parole dans la requête et associez les locuteurs aux voix :

gemini-api tts "Build succeeded. All integration tests passed." \
  --voice Aoede \
  --out ./public/audio/build-ok.wav

gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./public/audio/release-intro.wav

Musique et vidéo

Composez des morceaux originaux avec Lyria et générez des clips MP4 avec Gemini Omni :

gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \
  --out ./public/audio/bg-loop.mp3

gemini-api video "A drone shot of a mountain landscape at sunrise." \
  --aspect-ratio 16:9 \
  --resolution 1080p \
  --out ./public/video/mountain-sunrise.mp4

Par défaut, la commande video attend la fin de la génération et écrit le fichier MP4 sur le disque. Transmettez --async pour renvoyer immédiatement un ID d'interaction, puis exécutez gemini-api video --resume <id> --out <path> ultérieurement. Transmettez -i pour animer une image existante.

Génération de texte

gemini-api generate diffuse du texte vers stdout :

gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."

Ajoutez --stdin pour insérer du texte dans le prompt. Transmettez --previous-interaction-id pour poursuivre une interaction précédente.

Analyse et transcription de documents

analyze répond aux questions sur les PDF, les feuilles de calcul, les captures d'écran, les fichiers audio et vidéo, et les URL YouTube publiques. transcribe écrit une transcription formatée (md, text, json ou srt) sur le disque :

gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md

gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt

Transmettez -i plusieurs fois à analyze pour comparer des fichiers, par exemple des captures d'écran avant et après.

gemini-api envoie des fichiers locaux intégrés d'une taille maximale de 14 Mo (20 Mo après l'encodage en base64). Pour les fichiers plus volumineux, importez-les une fois avec files upload --wait et réutilisez l'URI files/<id> renvoyé :

FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)

gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json

Exécuter et gérer des agents

Votre agent de codage peut déléguer des tâches de recherche ou de bac à sable en plusieurs étapes à des agents gérés par Gemini, tels que l'agent Deep Research. Transmettez --background --stream=false pour obtenir immédiatement un ID d'interaction au lieu de maintenir un flux ouvert :

# Launch a Deep Research job in the background and capture its interaction ID
RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

# Check status or fetch the finished result while continuing other work
gemini-api agent status "$RESEARCH_ID" -o json

Exécutez gemini-api agent cancel <id> pour arrêter un job en cours d'exécution. Vous pouvez également lancer l'agent Antigravity dans un bac à sable distant avec agent run, ou gérer des agents personnalisés avec agent create, list, get et delete. Consultez Environnements pour configurer des bacs à sable d'agent.

Corps de requête personnalisés

Pour les options sans options dédiées, transmettez une charge utile JSON brute de l'API Interactions avec --body (intégrée ou en tant que @file.json). Transmettez --body pour définir les schémas response_format, les outils d'appel de fonction, generation_config ou "store": false. Exécutez d'abord gemini-api <command> --schema pour vérifier les champs valides :

# Inspect the JSON Schema for the request body
gemini-api generate --schema > generate-schema.json

# Return schema-constrained JSON and skip storing the interaction
cat logs.txt | gemini-api generate "Extract every error message from these logs." \
  --stdin \
  --body '{
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {"errors": {"type": "array", "items": {"type": "string"}}},
        "required": ["errors"]
      }
    },
    "store": false
  }'

--body fusionne avec les options de commande. Si les deux définissent la même clé, la commande échoue avec le code de sortie 2, de sorte que les entrées en conflit échouent rapidement.

Codes de sortie

Chaque commande renvoie un code de sortie typé afin que les scripts et les agents puissent gérer les échecs sans analyser le texte d'erreur. Par exemple, 3 signale un problème d'authentification et 2 signale une syntaxe de commande non valide :

Exécutez gemini-api --help-global pour lister les options globales partagées par chaque commande (authentification, sortie, réseau et diagnostics).

Limites

• Les commandes de streaming (generate et agent run) nécessitent --stream=false lorsqu'elles sont combinées avec -o json ou --jq pour renvoyer un seul objet de réponse JSON.
• Les entrées de fichiers -i intégrées sont limitées à 14 Mo de données de fichiers bruts (charge utile de requête de 20 Mo, y compris l'encodage en base64). Importez des fichiers volumineux avec gemini-api files upload. L'API Files supprime les fichiers importés au bout de 48 heures.
• gemini-api accepte les requêtes HTTP standards, le streaming SSE et l'interrogation asynchrone, mais pas les WebSockets bidirectionnels. Pour le streaming audio et vidéo en temps réel, utilisez l'API Live avec les SDK Google GenAI.

Étape suivante

• Configuration de l'agent de codage
• API Interactions
• Agents gérés Gemini
• gemini-api-cli sur GitHub