Gemini API CLI: haz que tu agente de código use Gemini para imágenes, vídeo, PDF y Deep Research

La CLI de Gemini API (gemini-api) es el cliente de línea de comandos de código abierto de Google para la API de Gemini, diseñado para agentes de codificación como Claude Code, Codex, Cursor y Antigravity. Instala un binario de Go, configura GEMINI_API_KEY y tu agente podrá generar imágenes, video, voz y música, analizar PDFs y grabaciones, transcribir audio a SRT y lanzar Deep Research en segundo plano.

Prueba Apidog hoy

A continuación: instalación, autenticación, los comandos que ejecutará tu agente, en qué se diferencia de Gemini CLI y cómo emparejarla con Apidog CLI. Cada bandera fue copiada de gemini-api --help en la versión 0.4.5, publicada el 30 de octubre de 2026.

¿Qué es la CLI de Gemini API?

Es un cliente sin estado, de binario único, para la API de Interactions de Google. Cada comando es una llamada HTTP: entra un prompt y sale una ruta de archivo, una transcripción, un análisis o un ID de interacción. No es un producto con el que chateas: es una herramienta que tu agente existente invoca cuando una tarea necesita Gemini.

La página de documentación oficial de Google la llama “una versión beta de código abierto que evoluciona junto con la API de Interactions”. El código vive en google-gemini/gemini-api-cli bajo Apache 2.0 y se ejecuta en macOS, Linux y Windows.

Esto es lo que gemini-api --help lista en 0.4.5, con el modelo predeterminado de cada comando:

Grupo	Comando	Qué hace	Modelo predeterminado
Crear	generate	Generación de texto y multimodal	gemini-3.8-flash
Crear	image	Generar o editar imágenes	gemini-nano-banana-2.1
Crear	video	Generar y editar video	gemini-omni-1.1-flash
Crear	tts / music	Voz y música	gemini-3.8-flash-tts / lyria-3.5
Comprender	analyze	Preguntas sobre PDFs, imágenes, audio, video, URLs de YouTube	gemini-3.8-flash
Comprender	transcribe	Audio o video a md, text, json o srt	gemini-3.5-transcribe
Gestionar	agent	Ejecutar modelos o agentes gestionados como Deep Research	definido por ejecución
Gestionar	files	Cargas de la API de archivos, retención de 48 horas	n/a

Gemini API CLI vs Gemini CLI

Los nombres se parecen, así que aquí va la diferencia. Gemini CLI (@google/gemini-cli) es un agente de codificación interactivo, una alternativa a Claude Code con el que conversas. La CLI de Gemini API (gemini-api) no tiene ningún bucle de agente: es una herramienta que otro agente ejecuta.

	Gemini API CLI	Gemini CLI
Binario	gemini-api	gemini
Rol	Una herramienta que tu agente llama	Un agente con el que hablas
Salida de medios	Imágenes, video, voz, música a disco	No es su enfoque
Ideal para	Dar a Claude Code, Codex o Cursor los modelos de Gemini	Usar Gemini como tu agente de codificación

Si trabajas en Claude Code o Codex y quieres los modelos de medios e investigación de Gemini dentro de ese flujo de trabajo, usa gemini-api. Es el mismo patrón que la CLI de OpenAI, apuntada a Google.

Cómo instalar la CLI de Gemini API

Elige una de las cuatro rutas del README.

macOS y 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

Binarios precompilados: descarga el archivo de tu plataforma desde GitHub Releases, verifícalo con checksums.txt y coloca gemini-api en tu PATH. Nosotros usamos el archivo Darwin_arm64; shasum -a 256 -c checksums.txt --ignore-missing imprimió OK.

Google advierte que pueden producirse cambios importantes entre versiones menores, así que fija una versión en CI. La documentación muestra el script de instalación con GEMINI_VERSION=<release-tag> colocado antes de bash.

Confirma la instalación:

gemini-api version
# gemini-api 0.4.5

Autenticación de Gemini API CLI

Crea una clave en Google AI Studio (nuestra guía para obtener una clave de API de Gemini gratis lo explica) y expórtala:

export GEMINI_API_KEY="YOUR_API_KEY"

En tu propia estación de trabajo puedes guardarla en su lugar:

gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami

configure almacena la clave en el llavero de tu sistema operativo (Keychain de macOS, Secret Service de Linux o Credential Manager de Windows). Agrega la bandera global --no-keyring para conservarla en ~/.config/gemini-api/config.yaml. whoami muestra qué credencial está activa y de dónde proviene.

Sin una clave configurada, gemini-api --help imprime una línea dirigida al propio agente: una clave de API “debe ser creada manualmente por el usuario en Google AI Studio. Detente y pídele al usuario que cree una”. Tu agente te preguntará en lugar de configurar una clave por su cuenta.

Previsualiza cualquier llamada con --dry-run

--dry-run valida las banderas e imprime la solicitud con las credenciales censuradas, sin llamada de red y sin leer el llavero. Funciona antes de que configures una clave; así verificamos cada ejemplo de este artículo.

Aquí tienes una ejecución en seco real de un trabajo de Deep Research en segundo plano:

Cada comando se envía a https://generativelanguage.googleapis.com/v1beta/interactions. Agrega -o json para obtener un objeto JSON por solicitud en stdout, que un agente puede analizar antes de gastar un solo token.

Comandos de Gemini API CLI que ejecutará tu agente

Generar y editar imágenes

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

Los comandos de medios escriben el archivo e imprimen solo su ruta, de modo que el agente la captura con $(...) y sigue construyendo. image también acepta --aspect-ratio y --image-size (512, 1K, 2K o 4K). El modelo predeterminado es Nano Banana 2.1; consulta nuestra guía de la API de Nano Banana 2.1 para saber en qué destaca.

Generar video, voz y música

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/

El video tarda más, así que video sondea por ti. Usa --async para recibir el identificador de operación de inmediato y --resume <id> para retomar el sondeo más tarde. --resolution es 720p por defecto.

Analizar PDFs, imágenes y URLs de 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 es repetible y acepta una ruta local, una URI files/<id> o una URL de YouTube. Las entradas en línea tienen un límite de unos 14 MB sin procesar. Para archivos más grandes, súbelos una vez y reutiliza la 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"

Los archivos subidos se eliminan después de 48 horas.

Transcribir audio y video

gemini-api transcribe -i interview.mp4 --format srt --out interview.srt

--format acepta md (predeterminado), text, json o srt. Agrega --no-speakers o --no-timestamps para eliminar cualquiera de los dos de la salida.

Ejecutar Deep Research en segundo plano

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 devuelve un ID de interacción de inmediato en lugar de mantener abierto un flujo. El agente guarda el ID, trabaja en otra cosa y vuelve a consultar con agent status. agent cancel detiene una ejecución. La ayuda de 0.4.5 también lista deep-research-max-preview-04-2026 y antigravity-preview-05-2026 como agentes gestionados.

Opciones que hacen que gemini-api sea seguro para agentes

Estas son las banderas globales que conviene incluir en las instrucciones de tu agente, todas de gemini-api --help-global:

• --agent-mode (o GEMINI_CLI_AGENT_MODE=1): errores JSON estructurados en stderr y salida TOON compacta en stdout.
• -o, --output-format: pretty, json, yaml, table o toon.
• -q, --jq: filtra la salida en línea, por ejemplo --jq '.id'.
• --no-interactive: sin prompts ni formularios TUI, algo que un agente sin interfaz necesita.
• --usage: el árbol de comandos completo como KDL legible por máquina.
• --schema (por comando): el Esquema JSON para una carga útil --body.

Los códigos de salida le dicen al agente qué falló sin analizar texto: 0 ok, 1 fallo en tiempo de ejecución o de API, 2 error de uso o validación, 3 autenticación. Un detalle: los comandos de transmisión (generate, agent run) necesitan --stream=false antes de que -o json o --jq devuelvan un único resultado analizable.

Dale a tu agente de codificación la CLI de Gemini API

El README de Google incluye un bloque listo para pegar en AGENTS.md, CLAUDE.md o .cursorrules. Recortado:

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.

Asegúrate de que GEMINI_API_KEY llegue al entorno del subproceso del agente. Después, pide como siempre: “Construye la página de destino, usa Gemini para una imagen de mascota y una voz en off de 20 segundos, e inicia una ejecución de Deep Research sobre productos competidores.” El agente elige los comandos.

Lo que no hace: voz ni video en tiempo real. No hay soporte para WebSocket, de modo que la API en vivo todavía requiere los SDK de GenAI.

Prueba la API que construyes con Apidog CLI

gemini-api le da a tu agente los modelos de Gemini. No sabe nada de tu propia API: el endpoint /summarize o /thumbnail con el que tu aplicación envuelve a Gemini, sus entornos o las aserciones que demuestran que una versión no se rompió. Ese es el trabajo de Apidog CLI, y el mismo agente puede ejecutar ambos.

Configúralo una vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Luego dale a tu agente un [REDACTED 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 , 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.

El agente verifica la respuesta de Gemini con `gemini-api`, luego lee el esquema de Apidog antes de escribir una carga útil, la valida, y crea y ejecuta el caso:

bash
apidog import --project --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 --file case.json
apidog run --test-case --project -e -r cli,json

`apidog test-case create --help` advierte de una trampa: el caso necesita un `categoryId` válido, así que lístalos primero con `apidog test-case category --project <id>`. Cambia `-r cli,json` por `-r junit` y la misma línea se ejecuta en CI. Si Claude Code es tu agente, empieza con [Apidog CLI en Claude Code](https://apidog.com/es/blog/apidog-cli-in-claude-code?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). El plan gratuito de Apidog cubre hasta 4 usuarios.

## Preguntas frecuentes

**¿La CLI de Gemini API es gratis?** La CLI en sí es gratuita y de código abierto bajo Apache 2.0. Cada llamada se factura a tu clave de API según los [precios normales de la API de Gemini](https://ai.google.dev/gemini-api/docs/pricing). Para saber qué cubre el nivel gratuito, consulta nuestra [guía del nivel gratuito de la API de Gemini](https://apidog.com/es/blog/gemini-api-free-tier?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).

**¿gemini-api es lo mismo que Gemini CLI?** No. Gemini CLI es un agente de codificación interactivo. `gemini-api` es una herramienta sin estado que otros agentes, scripts y trabajos de CI llaman para acceder a los modelos y agentes gestionados de Gemini.

**¿Puedo probar comandos sin una clave de API?** Sí. `--dry-run` valida el comando e imprime la solicitud exacta sin llamada de red y sin lectura del llavero. Cada ejemplo de este artículo fue verificado así en 0.4.5.

**¿Cómo manejo archivos de más de 14 MB?** Ejecuta `gemini-api files upload <file> --wait`, conserva el `files/<id>` devuelto y pásalo a `-i` en `analyze`, `transcribe`, `generate`, `image`, `video` o `agent run`. Las cargas expiran después de 48 horas.

**¿Debería fijar una versión?** Sí, en CI. Google indica que pueden producirse cambios importantes entre versiones menores mientras la CLI esté en beta.