La Gemini API CLI (gemini-api) est le client en ligne de commande open source de Google pour l'API Gemini, conçu pour les agents de codage comme Claude Code, Codex, Cursor et Antigravity. Installez un seul binaire Go, définissez GEMINI_API_KEY, et votre agent peut générer des images, de la vidéo, de la parole et de la musique, analyser des PDF et des enregistrements, transcrire de l'audio en SRT et lancer Deep Research en arrière-plan.
Ci-dessous : l'installation, l'authentification, les commandes que votre agent exécutera, en quoi elle diffère de Gemini CLI, et comment l'associer à Apidog CLI. Chaque option a été copiée depuis gemini-api --help sur la version 0.4.5, publiée le 30 octobre 2026.
Qu'est-ce que la Gemini API CLI ?
La Gemini API CLI est un client sans état, à binaire unique, pour l'Interactions API de Google. Chaque commande est un seul appel HTTP : un prompt entre, et un chemin de fichier, une transcription, une analyse ou un identifiant d'interaction sort. C'est un outil que votre agent existant appelle lorsqu'une tâche nécessite Gemini.
La page de documentation officielle de Google la présente comme « une version bêta open source qui évolue au rythme de l'Interactions API ». Le code se trouve sur google-gemini/gemini-api-cli sous licence Apache 2.0, et il fonctionne sur macOS, Linux et Windows.
Voici ce que gemini-api --help liste en 0.4.5, avec le modèle par défaut de chaque commande :
| Groupe | Commande | Ce qu'elle fait | Modèle par défaut |
|---|---|---|---|
| Créer | generate |
Génération de texte et multimodale | gemini-3.8-flash |
| Créer | image |
Générer ou modifier des images | gemini-nano-banana-2.1 |
| Créer | video |
Générer et modifier de la vidéo | gemini-omni-1.1-flash |
| Créer | tts / music |
Parole et musique | gemini-3.8-flash-tts / lyria-3.5 |
| Comprendre | analyze |
Questions sur des PDF, des images, de l'audio, de la vidéo, des URL YouTube | gemini-3.8-flash |
| Comprendre | transcribe |
Audio ou vidéo vers md, text, json ou srt | gemini-3.5-transcribe |
| Gérer | agent |
Exécuter des modèles ou des agents gérés tels que Deep Research | défini par exécution |
| Gérer | files |
Téléversements via la Files API, conservation de 48 heures | n/a |
Gemini API CLI vs Gemini CLI
Les noms sont proches, voici donc la distinction. Gemini CLI (@google/gemini-cli) est un agent de codage interactif, une alternative à Claude Code avec laquelle vous discutez. La Gemini API CLI (gemini-api) n'a aucune boucle d'agent. C'est un outil qu'un autre agent exécute.
| Gemini API CLI | Gemini CLI | |
|---|---|---|
| Binaire | gemini-api |
gemini |
| Rôle | Un outil que votre agent appelle | Un agent avec lequel vous discutez |
| Sortie média | Images, vidéo, parole, musique sur le disque | Ce n'est pas son point fort |
| Idéal pour | Donner les modèles Gemini à Claude Code, Codex ou Cursor | Utiliser Gemini comme agent de codage |
Si vous travaillez dans Claude Code ou Codex et souhaitez les modèles média et de recherche de Gemini au sein de ce flux de travail, utilisez gemini-api. C'est le même schéma que l'OpenAI CLI, dirigé vers Google.
Comment installer la Gemini API CLI
Choisissez l'une des quatre méthodes du README.
macOS et 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
Go :
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest
Binaires précompilés : téléchargez l'archive correspondant à votre plateforme depuis GitHub Releases, vérifiez-la par rapport à checksums.txt, et placez gemini-api dans votre PATH. Nous avons utilisé l'archive Darwin_arm64 ; shasum -a 256 -c checksums.txt --ignore-missing a affiché OK.
Google prévient que des changements majeurs peuvent survenir entre les versions mineures, alors épinglez une version dans votre CI. La documentation montre le script d'installation avec GEMINI_VERSION=<release-tag> placé avant bash.
Confirmez l'installation :
gemini-api version
# gemini-api 0.4.5
Authentification de la Gemini API CLI
Créez une clé dans Google AI Studio (notre guide pour obtenir une clé API Gemini gratuitement vous explique la procédure), puis exportez-la :
export GEMINI_API_KEY="YOUR_API_KEY"
Sur votre propre poste de travail, vous pouvez plutôt la stocker :
gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami
configure enregistre la clé dans le trousseau de votre système d'exploitation (macOS Keychain, Linux Secret Service ou Windows Credential Manager). Ajoutez l'option globale --no-keyring pour la conserver plutôt dans ~/.config/gemini-api/config.yaml. whoami indique quel identifiant est actif et d'où il provient.
Sans clé définie, gemini-api --help affiche une ligne destinée à l'agent lui-même : une clé API « doit être créée manuellement par l'utilisateur dans Google AI Studio. Arrêtez-vous et demandez à l'utilisateur d'en créer une ». Votre agent vous demandera donc plutôt que de configurer une clé de lui-même.
Prévisualiser n'importe quel appel avec --dry-run
--dry-run valide les options et affiche la requête avec les identifiants masqués, sans appel réseau et sans lecture du trousseau. Cela fonctionne avant même que vous ayez défini une clé, et c'est ainsi que nous avons vérifié chaque exemple ici.
Voici un véritable dry run d'une tâche Deep Research en arrière-plan :
Chaque commande envoie une requête POST à https://generativelanguage.googleapis.com/v1beta/interactions. Ajoutez -o json pour obtenir un objet JSON par requête sur stdout, qu'un agent peut analyser avant de dépenser le moindre token.
Les commandes de la Gemini API CLI que votre agent exécutera
Générer et modifier des images
gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg
gemini-api image "Add a winter scarf" -i ./assets/mascot.jpg --out ./assets/mascot-winter.jpg
Les commandes média écrivent le fichier et affichent uniquement son chemin, de sorte que l'agent le capture avec $(...) et continue sa tâche. image accepte également --aspect-ratio et --image-size (512, 1K, 2K ou 4K). Le modèle par défaut est Nano Banana 2.1 ; consultez notre guide de l'API Nano Banana 2.1 pour savoir ce qu'il fait bien.
Générer de la vidéo, de la parole et de la musique
gemini-api video "A slow camera move through a sunlit workshop" --resolution 1080p --out ./assets/
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api music "Warm ambient music for a product walkthrough" --out ./assets/
La vidéo prend plus de temps, donc video effectue le polling pour vous. Utilisez --async pour obtenir immédiatement le handle de l'opération et --resume <id> pour reprendre le polling plus tard. --resolution vaut 720p par défaut.
Analyser des PDF, des images et des URL YouTube
gemini-api analyze -i product-brief.pdf "What should we build first, and why?" > plan.md
gemini-api analyze -i before.png -i after.png "Summarize the visual design changes"
-i/--input est répétable et accepte un chemin local, un URI files/<id> ou une URL YouTube. Les entrées en ligne sont limitées à environ 14 Mo bruts. Pour les fichiers plus volumineux, téléversez-les une fois et réutilisez l'URI :
FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze -i "$FILE_URI" "List the key action items with timestamps"
Les fichiers téléversés sont supprimés au bout de 48 heures.
Transcrire de l'audio et de la vidéo
gemini-api transcribe -i interview.mp4 --format srt --out interview.srt
--format accepte md (par défaut), text, json ou srt. Ajoutez --no-speakers ou --no-timestamps pour retirer l'un ou l'autre de la sortie.
Lancer Deep Research en arrière-plan
ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
--agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$ID" --stream=false --output-format json
--background renvoie immédiatement un identifiant d'interaction au lieu de maintenir un flux ouvert. L'agent stocke l'identifiant, travaille sur autre chose, puis revient vérifier avec agent status. agent cancel arrête une exécution. L'aide de la version 0.4.5 liste également deep-research-max-preview-04-2026 et antigravity-preview-05-2026 comme agents gérés.
Les options qui rendent gemini-api sûr pour les agents
Voici les options globales qui méritent de figurer dans les instructions de votre agent, toutes issues de gemini-api --help-global :
--agent-mode(ouGEMINI_CLI_AGENT_MODE=1) : erreurs JSON structurées sur stderr et sortie TOON compacte sur stdout.-o, --output-format:pretty,json,yaml,tableoutoon.-q, --jq: filtrer la sortie en ligne, par exemple--jq '.id'.--no-interactive: aucun prompt ni formulaire TUI, ce dont un agent sans interface a besoin.--usage: l'arborescence complète des commandes en KDL lisible par machine.--schema(par commande) : le JSON Schema pour une charge utile--body.
Les codes de sortie indiquent à l'agent ce qui a échoué sans analyser de texte : 0 ok, 1 échec d'exécution ou de l'API, 2 erreur d'utilisation ou de validation, 3 authentification. Un piège : les commandes en streaming (generate, agent run) nécessitent --stream=false avant que -o json ou --jq ne renvoie un résultat unique et analysable.
Donnez la Gemini API CLI à votre agent de codage
Le README de Google fournit un bloc à coller dans AGENTS.md, CLAUDE.md ou .cursorrules. Version abrégée :
You have access to gemini-api through the shell.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run.
3. For JSON output or --jq on streaming commands, pass --stream=false --output-format json.
4. Capture returned file paths and interaction IDs to continue multi-step tasks.
Assurez-vous que GEMINI_API_KEY parvient à l'environnement du sous-processus de l'agent. Ensuite, adressez-vous à lui normalement : « Construis la page d'atterrissage, utilise Gemini pour une image de mascotte et une voix off de 20 secondes, et lance une session Deep Research sur les produits concurrents. » L'agent choisit les commandes.
Ce qu'elle ne fait pas : la voix ou la vidéo en temps réel. Il n'y a aucune prise en charge de WebSocket, donc la Live API nécessite toujours les SDK GenAI.
Testez l'API que vous développez avec Apidog CLI
gemini-api donne à votre agent les modèles Gemini. Elle ne sait rien de votre propre API : du point de terminaison /summarize ou /thumbnail que votre application enveloppe autour de Gemini, de ses environnements, ni des assertions qui prouvent qu'une version n'a rien cassé. C'est le rôle d'Apidog CLI, et le même agent peut exécuter les deux.
Configurez-le une fois :
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Ensuite, donnez à votre agent un seul prompt :
Use gemini-api to dry-run an analyze call on ./docs/sample-invoice.pdf, then run it for real.
Import ./openapi.yaml into Apidog project <id>, create a test case for POST /v1/invoices/extract
that uploads the same PDF and asserts a 200 and a non-empty "total" field, run it against the
staging environment, and summarize any failures.
L'agent vérifie la réponse de Gemini avec gemini-api, puis lit le schéma Apidog avant d'écrire une charge utile, la valide, et crée et exécute le cas de test :
apidog import --project <id> --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json
apidog test-case create --help signale un piège : le cas de test a besoin d'un categoryId valide, alors listez-les d'abord avec apidog test-case category --project <id>. Remplacez -r cli,json par -r junit et la même ligne s'exécute dans votre CI. Si Claude Code est votre agent, commencez par Apidog CLI dans Claude Code. Le forfait gratuit d'Apidog couvre jusqu'à 4 utilisateurs.
FAQ
La Gemini API CLI est-elle gratuite ? La CLI elle-même est gratuite et open source sous Apache 2.0. Chaque appel est facturé à votre clé API selon la tarification normale de l'API Gemini. Pour savoir ce que couvre le niveau gratuit, consultez notre guide du niveau gratuit de l'API Gemini.
gemini-api est-elle identique à Gemini CLI ? Non. Gemini CLI est un agent de codage interactif. gemini-api est un outil sans état que d'autres agents, scripts et tâches CI appellent pour accéder aux modèles Gemini et aux agents gérés.
Puis-je tester des commandes sans clé API ? Oui. --dry-run valide la commande et affiche la requête exacte sans aucun appel réseau ni lecture du trousseau. Chaque exemple de cet article a été vérifié de cette façon sur la version 0.4.5.
Comment gérer des fichiers de plus de 14 Mo ? Exécutez gemini-api files upload <file> --wait, conservez le files/<id> renvoyé, et passez-le à -i sur analyze, transcribe, generate, image, video ou agent run. Les téléversements expirent au bout de 48 heures.
Dois-je épingler une version ? Oui, dans la CI. Google indique que des changements majeurs peuvent survenir entre les versions mineures tant que la CLI est en bêta.