CLI da API Gemini: Deixe Seu Agente de Programação Chamar o Gemini para Imagens, Vídeos, PDFs e Pesquisa Profunda

A Gemini API CLI (gemini-api) é o cliente de linha de comando de código aberto do Google para a Gemini API, criado para agentes de codificação como Claude Code, Codex, Cursor e Antigravity. Instale um único binário Go, defina GEMINI_API_KEY, e seu agente poderá gerar imagens, vídeo, fala e música, analisar PDFs e gravações, transcrever áudio para SRT e iniciar o Deep Research em segundo plano.

A seguir: instalação, autenticação, os comandos que seu agente vai executar, como ele difere do Gemini CLI e como combiná-lo com o Apidog CLI. Todas as flags foram copiadas de gemini-api --help na versão 0.4.5, lançada em 30 de outubro de 2026.

O que é a Gemini API CLI?

A Gemini API CLI é um cliente sem estado e de binário único para a Interactions API do Google. Cada comando é uma chamada HTTP: entra um prompt e sai um caminho de arquivo, uma transcrição, uma análise ou um ID de interação. É uma ferramenta que seu agente atual chama quando uma tarefa precisa do Gemini.

A página de documentação oficial do Google a descreve como "uma versão beta de código aberto que evolui junto com a Interactions API". O código fica em google-gemini/gemini-api-cli sob Apache 2.0, e roda em macOS, Linux e Windows.

Veja o que gemini-api --help lista na 0.4.5, com o modelo padrão de cada comando:

Gemini API CLI vs Gemini CLI

Os nomes são parecidos, então aqui está a diferença. O Gemini CLI (@google/gemini-cli) é um agente de codificação interativo, uma alternativa ao Claude Code com a qual você conversa. A Gemini API CLI (gemini-api) não tem nenhum loop de agente. É uma ferramenta que outro agente executa.

Se você trabalha no Claude Code ou no Codex e quer os modelos de mídia e de pesquisa do Gemini dentro desse fluxo de trabalho, use gemini-api. É o mesmo padrão do OpenAI CLI, apontado para o Google.

Como instalar a Gemini API CLI

Escolha uma das quatro formas descritas no README.

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

Binários pré-compilados: baixe o arquivo compactado da sua plataforma em GitHub Releases, verifique-o com checksums.txt e coloque gemini-api no seu PATH. Usamos o arquivo Darwin_arm64; shasum -a 256 -c checksums.txt --ignore-missing retornou OK.

O Google avisa que mudanças incompatíveis podem surgir entre versões menores, então fixe uma versão no CI. A documentação mostra o script de instalação com GEMINI_VERSION=<release-tag> colocado antes de bash.

Confirme a instalação:

gemini-api version
# gemini-api 0.4.5

Autenticação da Gemini API CLI

Crie uma chave no Google AI Studio (nosso guia para obter uma chave da Gemini API gratuitamente explica o passo a passo) e então exporte-a:

export GEMINI_API_KEY="YOUR_API_KEY"

Na sua própria estação de trabalho, você pode armazená-la em vez disso:

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

configure salva a chave no chaveiro do seu sistema operacional (Keychain do macOS, Secret Service do Linux ou Gerenciador de Credenciais do Windows). Adicione a flag global --no-keyring para mantê-la em ~/.config/gemini-api/config.yaml. whoami mostra qual credencial está ativa e de onde ela veio.

Sem nenhuma chave definida, gemini-api --help imprime uma linha dirigida ao próprio agente: uma chave de API "deve ser criada manualmente pelo usuário no Google AI Studio. Pare e peça ao usuário que crie uma". Seu agente vai pedir a você em vez de configurar uma chave por conta própria.

Pré-visualize qualquer chamada com --dry-run

--dry-run valida as flags e imprime a requisição com as credenciais ocultadas, sem chamada de rede e sem leitura do chaveiro. Funciona antes de você definir uma chave, e foi assim que verificamos todos os exemplos aqui.

Veja um dry run real de uma tarefa de Deep Research em segundo plano:

Todos os comandos fazem POST para https://generativelanguage.googleapis.com/v1beta/interactions. Adicione -o json para obter um objeto JSON por requisição no stdout, que um agente pode analisar antes de gastar um token.

Comandos da Gemini API CLI que seu agente vai executar

Gerar e editar imagens

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

Os comandos de mídia gravam o arquivo e imprimem apenas o caminho dele, então o agente o captura com $(...) e continua construindo. image também aceita --aspect-ratio e --image-size (512, 1K, 2K ou 4K). O modelo padrão é o Nano Banana 2.1; veja nosso guia da API Nano Banana 2.1 para saber no que ele se destaca.

Gerar vídeo, fala e 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/

Vídeo demora mais, então video faz o polling por você. Use --async para obter o handle da operação imediatamente e --resume <id> para retomar o polling depois. --resolution tem 720p como padrão.

Analisar PDFs, imagens e URLs do 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 pode ser repetido e aceita um caminho local, uma URI files/<id> ou uma URL do YouTube. Entradas inline têm limite de cerca de 14 MB brutos. Para arquivos maiores, faça o upload uma vez e reutilize a 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"

Os arquivos enviados são excluídos após 48 horas.

Transcrever áudio e vídeo

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

--format aceita md (padrão), text, json ou srt. Adicione --no-speakers ou --no-timestamps para remover um dos dois da saída.

Executar o Deep Research em 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 retorna um ID de interação imediatamente em vez de manter um stream aberto. O agente armazena o ID, trabalha em outra coisa e verifica depois com agent status. agent cancel interrompe uma execução. A ajuda da 0.4.5 também lista deep-research-max-preview-04-2026 e antigravity-preview-05-2026 como agentes gerenciados.

Flags que tornam o gemini-api seguro para agentes

Estas são as flags globais que vale a pena colocar nas instruções do seu agente, todas de gemini-api --help-global:

• --agent-mode (ou GEMINI_CLI_AGENT_MODE=1): erros JSON estruturados no stderr e saída TOON compacta no stdout.
• -o, --output-format: pretty, json, yaml, table ou toon.
• -q, --jq: filtra a saída inline, por exemplo --jq '.id'.
• --no-interactive: sem prompts ou formulários TUI, o que um agente headless precisa.
• --usage: a árvore completa de comandos em KDL legível por máquina.
• --schema (por comando): o JSON Schema para um payload --body.

Os códigos de saída dizem ao agente o que deu errado sem precisar analisar texto: 0 ok, 1 falha de execução ou da API, 2 erro de uso ou validação, 3 autenticação. Uma pegadinha: comandos de streaming (generate, agent run) precisam de --stream=false antes de -o json ou --jq para dar um único resultado analisável.

Dê a Gemini API CLI ao seu agente de codificação

O README do Google traz um bloco para colar em AGENTS.md, CLAUDE.md ou .cursorrules. Resumido:

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.

Certifique-se de que GEMINI_API_KEY chegue ao ambiente do subprocesso do agente. Depois, faça o prompt como de costume: "Construa a landing page, use o Gemini para uma imagem de mascote e uma narração de 20 segundos, e inicie uma execução do Deep Research sobre produtos concorrentes." O agente escolhe os comandos.

O que ele não faz: voz ou vídeo em tempo real. Não há suporte a WebSocket, então a Live API ainda precisa dos SDKs GenAI.

Teste a API que você constrói com o Apidog CLI

gemini-api dá ao seu agente os modelos do Gemini. Ele não sabe nada sobre a sua própria API: o endpoint /summarize ou /thumbnail que seu app envolve em torno do Gemini, seus ambientes ou as asserções que provam que um lançamento não quebrou nada. Esse é o trabalho do Apidog CLI, e o mesmo agente pode executar os dois.

Configure uma 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

Depois, dê ao seu agente um único 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.

O agente verifica a resposta do Gemini com gemini-api, depois lê o schema do Apidog antes de escrever um payload, valida-o e cria e executa o 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 aponta uma armadilha: o caso precisa de um categoryId válido, então liste-os primeiro com apidog test-case category --project <id>. Troque -r cli,json por -r junit e a mesma linha roda no CI. Se o Claude Code é o seu agente, comece com Apidog CLI no Claude Code. O plano Free do Apidog cobre até 4 usuários.

Perguntas frequentes

A Gemini API CLI é gratuita? A CLI em si é gratuita e de código aberto sob Apache 2.0. Cada chamada é cobrada na sua chave de API conforme os preços normais da Gemini API. Para saber o que o nível gratuito cobre, veja nosso guia do nível gratuito da Gemini API.

O gemini-api é o mesmo que o Gemini CLI? Não. O Gemini CLI é um agente de codificação interativo. O gemini-api é uma ferramenta sem estado que outros agentes, scripts e jobs de CI chamam para acessar os modelos e agentes gerenciados do Gemini.

Posso testar comandos sem uma chave de API? Sim. --dry-run valida o comando e imprime a requisição exata sem chamada de rede e sem leitura do chaveiro. Todos os exemplos deste post foram verificados assim na 0.4.5.

Como lidar com arquivos maiores que 14 MB? Execute gemini-api files upload <file> --wait, guarde o files/<id> retornado e passe-o para -i em analyze, transcribe, generate, image, video ou agent run. Os uploads expiram após 48 horas.

Devo fixar uma versão? Sim, no CI. O Google diz que mudanças incompatíveis podem ocorrer entre versões menores enquanto a CLI estiver em beta.