Interfejs wiersza poleceń Gemini API

Interfejs wiersza poleceń Gemini API (gemini-api) to bezstanowy klient wiersza poleceń bez zależności, który został stworzony dla agentów AI z dostępem do powłoki (i może być używany ze skryptów i CI). Agent do kodowania może następnie generować tekst i multimedia, analizować pliki i przekazywać zadania agentom zarządzanym przez Gemini. Działa z Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes lub dowolnym środowiskiem powłoki.

Każda funkcja działa jako standardowe polecenie powłoki w Interactions API. Uruchom te same polecenia z podprocesu agenta, terminala lub potoku 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

Wybierz odpowiednie narzędzie Gemini

Używaj gemini-api, gdy agent lub skrypt musi wywołać Gemini bezpośrednio z powłoki bez dodawania kodu pakietu SDK do projektu. Używaj pakietów SDK i konfiguracji agenta kodowania, gdy integrujesz Gemini z aplikacją:

Jak to działa

Surowe wywołania REST i interaktywne interfejsy wiersza poleceń często powodują problemy z agentami kodującymi. Dane multimedialne Base64 wypełniają okno kontekstu, interaktywne prompty blokują podprocesy, a nieaktualne dane treningowe powodują halucynacje.

Cztery rozwiązania projektowe zapewniają niezawodność gemini-api dla agentów:

• Wyszukiwanie schematu offline: przekaż --usage, aby wydrukować drzewo poleceń (w formacie KDL), lub --schema, aby wydrukować schemat JSON dla żądań --body.
• Pliki na dysku, ścieżki w stdout: polecenia dotyczące multimediów i transkrypcji zapisują pliki na dysku i wyświetlają tylko ścieżkę wyjściową, dzięki czemu dane binarne nie są uwzględniane w kontekście.
• Uruchomienia próbne i ustrukturyzowane dane wyjściowe: --dry-run sprawdza dane wejściowe, ukrywa dane logowania i wyświetla podgląd żądania HTTP w trybie offline. Aby uzyskać dane wyjściowe w formacie czytelnym dla komputerów, przekaż -o json, -o toon lub --jq. Dodaj --agent-mode, aby zwracać błędy JSON w formacie uporządkowanym w stderr, i sprawdź kody wyjścia, aby obsłużyć błędy. Polecenia nigdy nie wyświetlają prośby, chyba że przekażesz --interactive.
• Domyślnie bezstanowe: polecenia nie zachowują ukrytego stanu lokalnego. Połącz wieloetapowe zadania bezpośrednio z --previous-interaction-id, przesłanym identyfikatorem URI files/<id> lub identyfikatorem interakcji w tle.

W przypadku -o json polecenia multimedialne nadal zapisują plik na dysku i wyświetlają metadane w stdout:

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

Rozpocznij

Zainstaluj interfejs wiersza poleceń, umieść gemini-api w PATH, ustaw GEMINI_API_KEY i dodaj reguły korzystania do agenta kodowania.

1. Instalowanie pliku binarnego

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. Konfigurowanie uwierzytelniania i weryfikacja

Utwórz klucz interfejsu API w Google AI Studio (patrz Klucze interfejsu API). Ustaw GEMINI_API_KEY w powłoce i środowisku podprocesu agenta:

export GEMINI_API_KEY="YOUR_API_KEY"

Na lokalnej stacji roboczej możesz zapisać klucz w pęku kluczy systemu operacyjnego (pęk kluczy macOS, usługa Secret Service w systemie Linux lub Credential Manager w systemie Windows). Aby zapisać klucz w ~/.config/gemini-api/config.yaml, przekaż --no-keyring:

# 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. Podaj instrukcje dla agenta

Dodaj ten fragment kodu do pliku AGENTS.md, CLAUDE.md, .cursorrules lub promptu systemowego projektu, aby agent kodowania wiedział, jak używać 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`.

Następnie poproś asystenta kodowania o pomoc w zwykły sposób:

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.

Polecenia

Uruchom gemini-api --help, aby wyświetlić listę wszystkich poleceń, lub gemini-api explore, aby przeglądać je interaktywnie.

Przepływy pracy

Każde polecenie domyślnie używa modelu odpowiedniego do danego zadania. Przekaż --model (-m), aby wybrać inny model. Uruchom gemini-api models, aby wyświetlić listę dostępnych opcji.

Generowanie i edytowanie obrazów

Agenty tworzące interfejsy internetowe lub mobilne mogą generować obiekty zastępcze, ikony i banery powitalne za pomocą Nano Banana. Przekaż wygenerowaną ścieżkę z -i, aby edytować obraz:

# 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

Przekaż -i kilka razy, aby połączyć obrazy referencyjne, np. postać i przewodnik po stylu.

Synteza mowy

gemini-api tts syntezuje dźwięk WAV 24 kHz na potrzeby wskazówek interfejsu, podglądów ułatwień dostępu i przewodników z narracją. Domyślny głos to Kore. Możesz wybrać inny za pomocą --voice. W przypadku dialogu między 2 osobami oznacz każdą wypowiedź w prompcie i przypisz rozmówców do głosów:

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

Muzyka i filmy

Twórz oryginalne utwory za pomocą Lyria i generuj klipy MP4 za pomocą 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

Domyślnie polecenie video czeka na zakończenie generowania i zapisuje plik MP4 na dysku. Przekaż --async, aby natychmiast zwrócić identyfikator interakcji, a potem uruchom gemini-api video --resume <id> --out <path>. Przekaż -i, aby animować istniejący obraz.

Generowanie tekstu

gemini-api generate przesyła strumieniowo tekst do stdout:

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

Dodaj --stdin, aby wstawić tekst do prompta. Przekaż --previous-interaction-id, aby kontynuować wcześniejszą interakcję.

Analiza i transkrypcja dokumentów

analyze odpowiada na pytania dotyczące plików PDF, arkuszy kalkulacyjnych, zrzutów ekranu, plików audio i wideo oraz publicznych adresów URL na YouTube. transcribe zapisuje sformatowaną transkrypcję (md, text, json lub srt) na dysku:

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

Przekaż -i wielokrotnie do analyze, aby porównać pliki, np. zrzuty ekranu przed i po.

gemini-api wysyła pliki lokalne w treści wiadomości o rozmiarze do 14 MB (20 MB po kodowaniu base64). W przypadku większych plików prześlij je raz za pomocą files upload --wait i użyj ponownie zwróconego identyfikatora URI files/<id>:

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

Uruchamianie agentów i zarządzanie nimi

Twój agent kodowania może przekazywać wieloetapowe badania lub zadania w piaskownicy zarządzanym agentom Gemini, takim jak agent Deep Research. Przekaż parametr --background --stream=false, aby natychmiast uzyskać identyfikator interakcji zamiast utrzymywać otwarty strumień:

# 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

Aby zatrzymać uruchomione zadanie, uruchom polecenie gemini-api agent cancel <id>. Możesz też uruchomić agenta Antigravity w zdalnej piaskownicy za pomocą agent run lub zarządzać agentami niestandardowymi za pomocą agent create, list, get i delete. Aby skonfigurować piaskownice agentów, zapoznaj się z artykułem o środowiskach.

Niestandardowe treści żądań

W przypadku opcji bez dedykowanych flag przekaż nieprzetworzony ładunek JSON Interactions API z flagą --body (wbudowany lub jako @file.json). Przekaż --body, aby ustawić schematy response_format, narzędzia do wywoływania funkcji, generation_config lub "store": false. Najpierw uruchom gemini-api <command> --schema, aby sprawdzić prawidłowe pola:

# 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 łączy się z flagami poleceń. Jeśli oba ustawiają ten sam klucz, polecenie kończy się niepowodzeniem z kodem wyjścia 2, dzięki czemu sprzeczne dane wejściowe szybko powodują błąd.

Kody wyjścia

Każde polecenie zwraca wpisany kod wyjścia, dzięki czemu skrypty i agenty mogą obsługiwać błędy bez analizowania tekstu błędu. Na przykład 3 oznacza problem z uwierzytelnianiem, a 2 – nieprawidłową składnię polecenia:

Uruchom gemini-api --help-global, aby wyświetlić listę globalnych flag udostępnianych przez każde polecenie (uwierzytelnianie, dane wyjściowe, sieć i diagnostyka).

Ograniczenia

• Polecenia przesyłania strumieniowego (generate i agent run) wymagają --stream=false, gdy są połączone z -o json lub --jq, aby zwrócić pojedynczy obiekt odpowiedzi JSON.
• Pliki -i wstawiane w treści mogą mieć maksymalnie 14 MB nieprzetworzonych danych (20 MB danych żądania, w tym kodowanie base64). Przesyłaj duże pliki za pomocą gemini-api files upload. Interfejs Files API usuwa przesłane pliki po 48 godzinach.
• gemini-api obsługuje standardowe żądania HTTP, strumieniowanie SSE i asynchroniczne odpytywanie, ale nie obsługuje dwukierunkowych protokołów WebSockets. W przypadku strumieniowego przesyłania głosu i obrazu w czasie rzeczywistym używaj interfejsu Live API z pakietami SDK Google GenAI.

Co dalej?

• Konfiguracja agenta kodującego
• Interactions API
• Zarządzani agenci Gemini
• gemini-api-cli na GitHubie