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.

A continuación: instalación, autenticación, los comandos que ejecutará tu agente, en qué se diferencia de Gemini CLI, y cómo emparejarlo 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?

La CLI de Gemini API es un cliente sin estado y 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. Es una herramienta que tu agente existente llama 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 para cada comando:

Gemini API CLI vs Gemini CLI

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

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 para tu plataforma desde GitHub Releases, verifícalo con checksums.txt, y coloca gemini-api en tu PATH. Usamos el archivo Darwin_arm64; shasum -a 256 -c checksums.txt --ignore-missing imprimió OK.

Google advierte que pueden ocurrir 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), luego expórtala:

export GEMINI_API_KEY="YOUR_API_KEY"

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

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

configure guarda 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 mantenerla en ~/.config/gemini-api/config.yaml en su lugar. 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 sí solo.

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 lectura del llavero. Funciona antes de que hayas configurado una clave, que es como verificamos cada ejemplo aquí.

Aquí hay 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 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, por lo que el agente lo 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 qué hace bien.

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, por lo que video sondea por ti. Usa --async para obtener el identificador de operación de inmediato y --resume <id> para retomar la 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 aproximadamente 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 un flujo abierto. El agente almacena 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 vale la pena poner 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, 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é salió mal 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 den un único resultado analizable.

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

El README de Google incluye un bloque 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. Luego pide como de costumbre: “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 o video en tiempo real. No hay soporte para WebSocket, por lo que la API en vivo todavía necesita 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 sobre tu propia API: el endpoint /summarize o /thumbnail que tu aplicación envuelve alrededor de Gemini, sus entornos, o las aserciones que prueban 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 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.

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

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 señala 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, comienza con Apidog CLI en Claude Code. 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. Para saber qué cubre el nivel gratuito, consulta nuestra guía del nivel gratuito de la API de Gemini.

¿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 en esta publicación fue verificado de esa manera 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 dice que pueden ocurrir cambios importantes entre versiones menores mientras la CLI está en beta.