CLI da API Gemini

A CLI da API Gemini (gemini-api) é um cliente de linha de comando sem estado e sem dependências, criado para agentes de IA com acesso ao shell (e utilizável em scripts e CI). Seu agente de programação pode gerar texto e mídia, analisar arquivos e delegar tarefas para agentes gerenciados do Gemini. Ele funciona com Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes ou qualquer ambiente shell.

Cada recurso é executado como um comando shell padrão na API Interactions. Execute os mesmos comandos em um subprocesso de agente, no terminal ou em um pipeline de CI:

# 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

Escolha a ferramenta certa do Gemini

Use gemini-api quando um agente ou script precisar chamar o Gemini diretamente do shell sem adicionar o código do SDK ao projeto. Use os SDKs e a configuração do agente de programação ao criar o Gemini em um aplicativo:

Como funciona

Chamadas REST brutas e CLIs interativas geralmente causam problemas para agentes de programação. A mídia em Base64 preenche a janela de contexto, os comandos interativos bloqueiam subprocessos e os dados de treinamento desatualizados causam flags alucinadas.

Quatro opções de design mantêm o gemini-api confiável para os agentes:

• Pesquisa de esquema off-line: transmita --usage para imprimir a árvore de comandos (em KDL) ou --schema para imprimir o esquema JSON para solicitações --body.
• Arquivos no disco, caminhos em stdout: os comandos de mídia e transcrição gravam arquivos no disco e mostram apenas o caminho de saída, mantendo os dados binários fora do contexto.
• Simulações e saída estruturada: o --dry-run valida entradas, oculta credenciais e mostra uma prévia da solicitação HTTP off-line. Transmita -o json, -o toon ou --jq para saída legível por máquina. Adicione --agent-mode para retornar erros JSON estruturados em stderr e verifique os códigos de saída para lidar com falhas. Os comandos nunca solicitam, a menos que você transmita --interactive.
• Sem estado por padrão: os comandos não mantêm nenhum estado local oculto. Encadeie trabalhos de várias etapas explicitamente com --previous-interaction-id, um URI files/<id> enviado por upload ou um ID de interação em segundo plano.

Com -o json, os comandos de mídia ainda gravam o arquivo no disco e mostram os metadados em stdout:

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

Primeiros passos

Instale a CLI, coloque gemini-api no PATH, defina GEMINI_API_KEY e adicione regras de uso ao agente de programação.

1. Instalar o binário

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. Configurar a autenticação e verificar

Crie uma chave de API no Google AI Studio (consulte Chaves de API). Defina GEMINI_API_KEY no shell e no ambiente de subprocesso do agente:

export GEMINI_API_KEY="YOUR_API_KEY"

Em uma estação de trabalho local, é possível salvar a chave no conjunto de chaves do SO (conjunto de chaves do macOS, serviço secreto do Linux ou Gerenciador de credenciais do Windows). Transmita --no-keyring para armazenar a chave em ~/.config/gemini-api/config.yaml:

# 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. Dê instruções ao seu agente

Adicione este snippet ao AGENTS.md, CLAUDE.md, .cursorrules ou comando do sistema do seu projeto para que o agente de programação saiba como usar o 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`.

Em seguida, envie um comando para o agente de programação como de costume:

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.

Comandos

Execute gemini-api --help para listar todos os comandos ou gemini-api explore para navegar por eles de forma interativa.

Fluxos de trabalho

Cada comando usa como padrão um modelo adequado para a tarefa. Transmita --model (-m) para escolher um modelo diferente. Execute gemini-api models para listar as opções disponíveis.

Geração e edição de imagens

Os agentes que criam interfaces da Web ou para dispositivos móveis podem gerar marcadores de posição, ícones e imagens principais com o Nano Banana. Transmita um caminho gerado de volta com -i para editar a imagem:

# 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

Transmita -i várias vezes para combinar imagens de referência, como um personagem e um guia de estilo.

Síntese de fala

O gemini-api tts sintetiza áudio WAV de 24 kHz para dicas de interface, prévias de acessibilidade e tutoriais narrados. A voz padrão é Kore. Escolha outra com --voice. Para diálogos com dois falantes, rotule cada turno no comando e mapeie os falantes para as vozes:

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

Música e vídeo

Componha músicas originais com o Lyria e gere clipes em MP4 com o 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

Por padrão, o comando video aguarda a conclusão da geração e grava o arquivo MP4 no disco. Transmita --async para retornar um ID de interação imediatamente e, em seguida, execute gemini-api video --resume <id> --out <path> mais tarde. Transmita -i para animar uma imagem atual.

Geração de texto

gemini-api generate transmite texto para stdout:

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

Adicione --stdin para canalizar o texto para o comando. Transmita --previous-interaction-id para continuar uma interação anterior.

Análise e transcrição de documentos

analyze responde a perguntas sobre PDFs, planilhas, capturas de tela, arquivos de áudio e vídeo e URLs públicos do YouTube. transcribe grava uma transcrição formatada (md, text, json ou srt) no disco:

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

Transmita -i várias vezes para analyze para comparar arquivos, como capturas de tela de antes e depois.

gemini-api envia arquivos locais inline de até 14 MB (20 MB após a codificação base64). Para arquivos maiores, faça upload uma vez com files upload --wait e reutilize o URI files/<id> retornado:

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

Executar e gerenciar agentes

Seu agente de programação pode delegar pesquisas de várias etapas ou tarefas em sandbox para agentes gerenciados do Gemini, como o agente do Deep Research. Transmita --background --stream=false para receber um ID de interação imediatamente em vez de manter um stream aberto:

# 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

Execute gemini-api agent cancel <id> para interromper um job em execução. Também é possível iniciar o agente do Antigravity em um sandbox remoto com agent run ou gerenciar agentes personalizados com agent create, list, get e delete. Consulte Ambientes para configurar sandboxes de agentes.

Corpos de solicitação personalizados

Para opções sem flags dedicadas, transmita um payload JSON bruto da API Interactions com --body (inline ou como @file.json). Transmita --body para definir esquemas response_format, ferramentas de chamada de função, generation_config ou "store": false. Execute gemini-api <command> --schema primeiro para verificar os campos válidos:

# 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 se mescla com as flags de comando. Se ambos definirem a mesma chave, o comando falhará com o código de saída 2 para que as entradas conflitantes falhem rapidamente.

Códigos de saída

Cada comando retorna um código de saída digitado para que scripts e agentes possam lidar com falhas sem analisar o texto do erro. Por exemplo, 3 indica um problema de autenticação, e 2 indica uma sintaxe de comando inválida:

Execute gemini-api --help-global para listar as flags globais compartilhadas por todos os comandos (autenticação, saída, rede e diagnóstico).

Limitações

• Os comandos de streaming (generate e agent run) exigem --stream=false quando combinados com -o json ou --jq para retornar um único objeto de resposta JSON.
• As entradas de arquivo -i inline são limitadas a 14 MB de dados de arquivo brutos (payload de solicitação de 20 MB, incluindo codificação base64). Fazer upload de arquivos grandes com gemini-api files upload. A API Files exclui os arquivos enviados após 48 horas.
• O gemini-api é compatível com solicitações HTTP padrão, streaming de SSE e sondagem assíncrona, mas não com WebSockets bidirecionais. Para streaming de voz e vídeo em tempo real, use a API Live com os SDKs de IA generativa do Google.

A seguir

• Configuração do agente de programação
• API Interactions
• Agentes gerenciados do Gemini
• gemini-api-cli no GitHub