Interfaccia a riga di comando dell'API Gemini

L'interfaccia a riga di comando dell'API Gemini (gemini-api) è un client a riga di comando stateless e senza dipendenze creato per gli agenti AI con accesso alla shell (e utilizzabile da script e CI). L'agente di programmazione può quindi generare testo e contenuti multimediali, analizzare file e delegare attività agli agenti gestiti da Gemini. Funziona con Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes o qualsiasi ambiente shell.

Ogni funzionalità viene eseguita come un comando shell standard nell'API Interactions. Esegui gli stessi comandi da un sottoprocesso dell'agente, dal terminale o da una pipeline 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

Scegli lo strumento Gemini giusto

Utilizza gemini-api quando un agente o uno script deve chiamare Gemini direttamente dalla shell senza aggiungere il codice dell'SDK al progetto. Utilizza gli SDK e la configurazione dell'agente di programmazione quando integri Gemini in un'applicazione:

Come funziona

Le chiamate REST non elaborate e le CLI interattive spesso causano problemi agli agenti di programmazione. I contenuti multimediali in Base64 riempiono la finestra di contesto, i prompt interattivi bloccano i sottoprocessi e i dati di addestramento obsoleti causano flag di allucinazione.

Quattro scelte di progettazione mantengono gemini-api affidabile per gli agenti:

• Ricerca dello schema offline: passa --usage per stampare l'albero dei comandi (in KDL) o --schema per stampare lo schema JSON per le richieste --body.
• File su disco, percorsi su stdout: i comandi di contenuti multimediali e trascrizione scrivono i file su disco e stampano solo il percorso di output, mantenendo i dati binari fuori contesto.
• Dry run e output strutturato: --dry-run convalida gli input, oscura le credenziali e visualizza l'anteprima della richiesta HTTP offline. Passa -o json, -o toon o --jq per l'output leggibile da macchina. Aggiungi --agent-mode per restituire errori JSON strutturati su stderr e controlla i codici di uscita per gestire gli errori. I comandi non richiedono mai l'intervento dell'utente, a meno che non passi --interactive.
• Stateless per impostazione predefinita: i comandi non mantengono uno stato locale nascosto. Concatena esplicitamente il lavoro in più passaggi con --previous-interaction-id, un URI files/<id> caricato o un ID interazione in background.

Con -o json, i comandi multimediali scrivono comunque il file sul disco e stampano i metadati su stdout:

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

Inizia

Installa l'interfaccia a riga di comando, inserisci gemini-api nel tuo PATH, imposta GEMINI_API_KEY e aggiungi regole di utilizzo all'agente di programmazione.

1. Installa il programma binario

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. Configura l'autenticazione e verifica

Crea una chiave API in Google AI Studio (consulta Chiavi API). Imposta GEMINI_API_KEY nella shell e nell'ambiente del sottoprocesso dell'agente:

export GEMINI_API_KEY="YOUR_API_KEY"

Su una workstation locale, puoi salvare la chiave nel portachiavi del sistema operativo (Portachiavi macOS, Secret Service di Linux o Gestore delle credenziali di Windows). Passa --no-keyring per archiviare la chiave in ~/.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. Dai istruzioni all'agente

Aggiungi questo snippet al AGENTS.md, CLAUDE.md, .cursorrules o al prompt di sistema del tuo progetto in modo che l'agente di programmazione sappia come utilizzare 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`.

Poi, chiedi all'agente di programmazione come di consueto:

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.

Comandi

Esegui gemini-api --help per elencare tutti i comandi o gemini-api explore per sfogliarli in modo interattivo.

Workflows

Ogni comando utilizza per impostazione predefinita un modello adatto alla sua attività. Passa --model (-m) per scegliere un modello diverso. Esegui gemini-api models per elencare le opzioni disponibili.

Generazione e modifica di immagini

Gli agenti che creano UI web o mobile possono generare segnaposto, icone e immagini hero con Nano Banana. Passa un percorso generato con -i per modificare l'immagine:

# 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

Passa -i più volte per combinare le immagini di riferimento, ad esempio un personaggio e una guida di stile.

Sintesi vocale

gemini-api tts sintetizza l'audio WAV a 24 kHz per i segnali della UI, le anteprime di accessibilità e le procedure dettagliate narrate. La voce predefinita è Kore; scegline un'altra con --voice. Per un dialogo tra due persone, etichetta ogni turno nel prompt e mappa le persone che parlano alle voci:

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

Musica e video

Componi tracce originali con Lyria e genera clip MP4 con 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

Per impostazione predefinita, il comando video attende il completamento della generazione e scrive il file MP4 sul disco. Passa --async per restituire immediatamente un ID interazione, quindi esegui gemini-api video --resume <id> --out <path> in un secondo momento. Passa -i per animare un'immagine esistente.

Generazione di testo

gemini-api generate trasmette il testo a stdout:

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

Aggiungi --stdin per inserire il testo nel prompt. Passa --previous-interaction-id per continuare un'interazione precedente.

Analisi e trascrizione dei documenti

analyze risponde a domande su PDF, fogli di lavoro, screenshot, file audio e video e URL di YouTube pubblici. transcribe scrive una trascrizione formattata (md, text, json o srt) sul 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

Passa -i più volte a analyze per confrontare i file, ad esempio gli screenshot prima e dopo.

gemini-api invia file locali in linea fino a 14 MB (20 MB dopo la codifica base64). Per i file più grandi, caricali una volta con files upload --wait e riutilizza l'URI files/<id> restituito:

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

Esegui e gestisci gli agenti

Il tuo agente di programmazione può delegare ricerche in più passaggi o attività in sandbox agli agenti gestiti da Gemini, come l'agente Deep Research. Passa --background --stream=false per ottenere immediatamente un ID interazione anziché tenere aperto uno stream:

# 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

Esegui gemini-api agent cancel <id> per interrompere un job in esecuzione. Puoi anche avviare l'agente Antigravity in una sandbox remota con agent run o gestire gli agenti personalizzati con agent create, list, get e delete. Consulta Ambienti per configurare le sandbox degli agenti.

Corpi delle richieste personalizzati

Per le opzioni senza flag dedicati, passa un payload JSON dell'API Interactions non elaborato con --body (incorporato o come @file.json). Passa --body per impostare gli schemi response_format, gli strumenti di chiamata di funzione, generation_config o "store": false. Esegui prima gemini-api <command> --schema per verificare i campi validi:

# 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 si unisce ai flag dei comandi. Se entrambi impostano la stessa chiave, il comando non va a buon fine con il codice di uscita 2, in modo che gli input in conflitto vengano interrotti rapidamente.

Codici di uscita

Ogni comando restituisce un codice di uscita tipizzato, in modo che gli script e gli agenti possano gestire gli errori senza analizzare il testo dell'errore. Ad esempio, 3 segnala un problema di autenticazione e 2 segnala una sintassi del comando non valida:

Esegui gemini-api --help-global per elencare i flag globali condivisi da ogni comando (autenticazione, output, rete e diagnostica).

Limitazioni

• I comandi di streaming (generate e agent run) richiedono --stream=false se combinati con -o json o --jq per restituire un singolo oggetto di risposta JSON.
• Gli input di file -i incorporati hanno un limite di 14 MB di dati di file non elaborati (payload della richiesta di 20 MB, inclusa la codifica base64). Carica file di grandi dimensioni con gemini-api files upload. L'API Files elimina i file caricati dopo 48 ore.
• gemini-api supporta le richieste HTTP standard, lo streaming SSE e il polling asincrono, non i WebSocket bidirezionali. Per lo streaming di voce e video in tempo reale, utilizza l'API Live con gli SDK Google GenAI.

Passaggi successivi

• Configurazione dell'agente di programmazione
• API Interactions
• Agenti gestiti di Gemini
• gemini-api-cli su GitHub