Gemini API CLI: Coding-Agent ruft Gemini für Bilder, Videos, PDFs und Deep Research auf

Die Gemini API CLI (gemini-api) ist Googles quelloffener Kommandozeilen-Client für die Gemini API, entwickelt für Coding-Agents wie Claude Code, Codex, Cursor und Antigravity. Installieren Sie ein einziges Go-Binary, setzen Sie GEMINI_API_KEY, und Ihr Agent kann Bilder, Video, Sprache und Musik generieren, PDFs und Aufnahmen analysieren, Audio in SRT transkribieren und Deep Research im Hintergrund starten.

Testen Sie Apidog noch heute

Im Folgenden: Installation, Authentifizierung, die Befehle, die Ihr Agent ausführt, wie sich das Tool von der Gemini CLI unterscheidet und wie man es mit der Apidog CLI kombiniert. Jedes Flag wurde aus gemini-api --help in Version 0.4.5 übernommen, veröffentlicht am 30. Oktober 2026.

Was ist die Gemini API CLI?

Die Gemini API CLI ist ein zustandsloser Client als einzelnes Binary für Googles Interactions API. Jeder Befehl ist ein einziger HTTP-Aufruf: Ein Prompt geht hinein, und ein Dateipfad, ein Transkript, eine Analyse oder eine Interaction-ID kommt heraus. Es ist ein Tool, das Ihr vorhandener Agent aufruft, wenn eine Aufgabe Gemini benötigt.

Googles offizielle Dokumentationsseite nennt es „ein Open-Source-Beta-Release, das sich zusammen mit der Interactions API weiterentwickelt". Der Code liegt unter google-gemini/gemini-api-cli unter Apache 2.0 und läuft auf macOS, Linux und Windows.

Hier ist, was gemini-api --help in 0.4.5 auflistet, mit dem Standardmodell für jeden Befehl:

Gruppe	Befehl	Was er tut	Standardmodell
Erstellen	generate	Text- und multimodale Generierung	gemini-3.8-flash
Erstellen	image	Bilder generieren oder bearbeiten	gemini-nano-banana-2.1
Erstellen	video	Videos generieren und bearbeiten	gemini-omni-1.1-flash
Erstellen	tts / music	Sprache und Musik	gemini-3.8-flash-tts / lyria-3.5
Verstehen	analyze	Fragen zu PDFs, Bildern, Audio, Video, YouTube-URLs	gemini-3.8-flash
Verstehen	transcribe	Audio oder Video nach md, text, json oder srt	gemini-3.5-transcribe
Verwalten	agent	Modelle oder verwaltete Agents wie Deep Research ausführen	pro Lauf festgelegt
Verwalten	files	Uploads über die Files API, 48 Stunden Aufbewahrung	n/a

Gemini API CLI vs. Gemini CLI

Die Namen sind ähnlich, daher hier die Abgrenzung. Gemini CLI (@google/gemini-cli) ist ein interaktiver Coding-Agent, eine Claude-Code-Alternative, mit der Sie chatten. Die Gemini API CLI (gemini-api) hat überhaupt keine Agent-Schleife. Sie ist ein Tool, das ein anderer Agent ausführt.

	Gemini API CLI	Gemini CLI
Binary	gemini-api	gemini
Rolle	Ein Tool, das Ihr Agent aufruft	Ein Agent, mit dem Sie sprechen
Medienausgabe	Bilder, Video, Sprache, Musik auf die Festplatte	Nicht sein Fokus
Am besten für	Claude Code, Codex oder Cursor Geminis Modelle zur Verfügung stellen	Gemini als Ihren Coding-Agenten verwenden

Wenn Sie in Claude Code oder Codex arbeiten und Geminis Medien- und Recherchemodelle in diesem Workflow nutzen möchten, verwenden Sie gemini-api. Es ist dasselbe Muster wie bei der OpenAI CLI, nur auf Google ausgerichtet.

So installieren Sie die Gemini API CLI

Wählen Sie einen von vier Wegen aus dem README.

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

Vorgefertigte Binaries: Laden Sie das Archiv für Ihre Plattform von GitHub Releases herunter, prüfen Sie es gegen checksums.txt und legen Sie gemini-api in Ihren PATH. Wir haben das Darwin_arm64-Archiv verwendet; shasum -a 256 -c checksums.txt --ignore-missing gab OK aus.

Google warnt, dass zwischen Minor-Versionen Breaking Changes auftreten können, daher sollten Sie in CI eine Release-Version pinnen. Die Doku zeigt das Installationsskript mit GEMINI_VERSION=<release-tag> vor bash.

Bestätigen Sie die Installation:

gemini-api version
# gemini-api 0.4.5

Authentifizierung der Gemini API CLI

Erstellen Sie einen Schlüssel in Google AI Studio (unser Leitfaden zum Erhalten eines kostenlosen Gemini API-Schlüssels führt Sie durch), und exportieren Sie ihn dann:

export GEMINI_API_KEY="YOUR_API_KEY"

Auf Ihrer eigenen Workstation können Sie ihn stattdessen speichern:

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

configure speichert den Schlüssel im Schlüsselbund Ihres Betriebssystems (macOS Keychain, Linux Secret Service oder Windows Credential Manager). Fügen Sie das globale Flag --no-keyring hinzu, um ihn stattdessen in ~/.config/gemini-api/config.yaml zu behalten. whoami zeigt, welche Anmeldeinformationen aktiv sind und woher sie stammen.

Ohne gesetzten Schlüssel gibt gemini-api --help eine Zeile aus, die an den Agenten selbst gerichtet ist: Ein API-Schlüssel „muss vom Benutzer manuell in Google AI Studio erstellt werden. Hören Sie auf und bitten Sie den Benutzer, einen zu erstellen." Ihr Agent wird Sie fragen, anstatt selbst einen Schlüssel zu konfigurieren.

Jeden Aufruf mit --dry-run vorab prüfen

--dry-run validiert Flags und gibt die Anfrage mit geschwärzten Anmeldeinformationen aus, ohne Netzwerkaufruf und ohne Zugriff auf den Schlüsselbund. Es funktioniert, bevor Sie einen Schlüssel gesetzt haben, und so haben wir jedes Beispiel hier geprüft.

Hier ist ein echter Dry Run eines Deep-Research-Jobs im Hintergrund:

Jeder Befehl sendet einen POST an https://generativelanguage.googleapis.com/v1beta/interactions. Fügen Sie -o json hinzu, um ein JSON-Objekt pro Anfrage auf stdout zu erhalten, das ein Agent parsen kann, bevor er ein Token verbraucht.

Gemini API CLI-Befehle, die Ihr Agent ausführen wird

Bilder generieren und bearbeiten

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

Medienbefehle schreiben die Datei und geben nur ihren Pfad aus, sodass der Agent ihn mit $(...) erfasst und weiterarbeitet. image akzeptiert außerdem --aspect-ratio und --image-size (512, 1K, 2K oder 4K). Das Standardmodell ist Nano Banana 2.1; lesen Sie unseren Nano Banana 2.1 API-Leitfaden, um zu erfahren, worin es gut ist.

Video, Sprache und Musik generieren

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/

Video dauert länger, daher fragt video für Sie nach (Polling). Verwenden Sie --async, um sofort das Operation-Handle zu erhalten, und --resume <id>, um das Polling später wieder aufzunehmen. --resolution ist standardmäßig 720p.

PDFs, Bilder und YouTube-URLs analysieren

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 ist wiederholbar und akzeptiert einen lokalen Pfad, eine files/<id>-URI oder eine YouTube-URL. Inline-Eingaben sind auf etwa 14 MB Rohdaten begrenzt. Für größere Dateien laden Sie sie einmal hoch und verwenden die URI wieder:

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"

Hochgeladene Dateien werden nach 48 Stunden gelöscht.

Audio und Video transkribieren

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

--format akzeptiert md (Standard), text, json oder srt. Fügen Sie --no-speakers oder --no-timestamps hinzu, um das jeweilige Element aus der Ausgabe zu entfernen.

Deep Research im Hintergrund ausführen

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 gibt sofort eine Interaction-ID zurück, anstatt einen Stream offen zu halten. Der Agent speichert die ID, arbeitet an etwas anderem und fragt später mit agent status nach. agent cancel stoppt einen Lauf. Die Hilfe zu 0.4.5 listet außerdem deep-research-max-preview-04-2026 und antigravity-preview-05-2026 als verwaltete Agents auf.

Flags, die gemini-api sicher für Agents machen

Dies sind die globalen Flags, die es wert sind, in die Anweisungen Ihres Agenten aufgenommen zu werden, alle aus gemini-api --help-global:

• --agent-mode (oder GEMINI_CLI_AGENT_MODE=1): strukturierte JSON-Fehler auf stderr und kompakte TOON-Ausgabe auf stdout.
• -o, --output-format: pretty, json, yaml, table oder toon.
• -q, --jq: Ausgabe direkt filtern, zum Beispiel --jq '.id'.
• --no-interactive: keine Eingabeaufforderungen oder TUI-Formulare, was ein Headless-Agent benötigt.
• --usage: der vollständige Befehlsbaum als maschinenlesbares KDL.
• --schema (pro Befehl): das JSON-Schema für eine --body-Nutzlast.

Exit-Codes sagen dem Agenten, was schiefgelaufen ist, ohne Text zu parsen: 0 ok, 1 Laufzeit- oder API-Fehler, 2 Nutzungs- oder Validierungsfehler, 3 Authentifizierung. Eine Stolperfalle: Streaming-Befehle (generate, agent run) benötigen --stream=false, bevor -o json oder --jq ein einzelnes parsebares Ergebnis liefern.

Geben Sie Ihrem Coding-Agenten die Gemini API CLI

Googles README enthält einen Block zum Einfügen in AGENTS.md, CLAUDE.md oder .cursorrules. Gekürzt:

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.

Stellen Sie sicher, dass GEMINI_API_KEY in der Subprozess-Umgebung des Agenten ankommt. Geben Sie dann wie gewohnt einen Prompt ein: „Baue die Landingpage, verwende Gemini für ein Maskottchen-Bild und ein 20-sekündiges Voiceover und starte einen Deep-Research-Lauf zu Konkurrenzprodukten." Der Agent wählt die Befehle aus.

Was es nicht tut: Echtzeit-Voice oder -Video. Es gibt keine WebSocket-Unterstützung, daher benötigt die Live API weiterhin die GenAI SDKs.

Testen Sie die API, die Sie bauen, mit der Apidog CLI

gemini-api gibt Ihrem Agenten Geminis Modelle. Es weiß nichts über Ihre eigene API: den /summarize- oder /thumbnail-Endpunkt, den Ihre App um Gemini herumlegt, seine Umgebungen oder die Assertions, die beweisen, dass ein Release nichts kaputt gemacht hat. Das ist die Aufgabe der Apidog CLI, und derselbe Agent kann beides ausführen.

Richten Sie es einmal ein:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Geben Sie Ihrem Agenten dann einen [REDACTED 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 , 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.

Der Agent prüft Geminis Antwort mit `gemini-api`, liest dann das Apidog-Schema, bevor er eine Nutzlast schreibt, validiert sie und erstellt und führt den Testfall aus:

bash
apidog import --project --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 --file case.json
apidog run --test-case --project -e -r cli,json

`apidog test-case create --help` weist auf eine Falle hin: Der Testfall benötigt eine gültige `categoryId`, also listen Sie diese zuerst mit `apidog test-case category --project <id>` auf. Ersetzen Sie `-r cli,json` durch `-r junit`, und dieselbe Zeile läuft in CI. Wenn Claude Code Ihr Agent ist, beginnen Sie mit [Apidog CLI in Claude Code](https://apidog.com/de/blog/apidog-cli-in-claude-code?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation). Der kostenlose Tarif von Apidog deckt bis zu 4 Benutzer ab.

## FAQ

**Ist die Gemini API CLI kostenlos?** Die CLI selbst ist kostenlos und quelloffen unter Apache 2.0. Jeder Aufruf wird über Ihren API-Schlüssel gemäß der normalen [Gemini API-Preisgestaltung](https://ai.google.dev/gemini-api/docs/pricing) abgerechnet. Was der kostenlose Tarif abdeckt, erfahren Sie in unserem [Leitfaden zum kostenlosen Gemini API-Tarif](https://apidog.com/de/blog/gemini-api-free-tier?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).

**Ist gemini-api dasselbe wie Gemini CLI?** Nein. Gemini CLI ist ein interaktiver Coding-Agent. `gemini-api` ist ein zustandsloses Tool, das andere Agents, Skripte und CI-Jobs aufrufen, um Gemini-Modelle und verwaltete Agents zu erreichen.

**Kann ich Befehle ohne API-Schlüssel testen?** Ja. `--dry-run` validiert den Befehl und gibt die exakte Anfrage aus, ohne Netzwerkaufruf und ohne Zugriff auf den Schlüsselbund. Jedes Beispiel in diesem Beitrag wurde so in 0.4.5 geprüft.

**Wie gehe ich mit Dateien über 14 MB um?** Führen Sie `gemini-api files upload <file> --wait` aus, behalten Sie die zurückgegebene `files/<id>` und übergeben Sie sie an `-i` bei `analyze`, `transcribe`, `generate`, `image`, `video` oder `agent run`. Uploads verfallen nach 48 Stunden.

**Sollte ich eine Version pinnen?** Ja, in CI. Google sagt, dass Breaking Changes zwischen Minor-Versionen auftreten können, solange die CLI in der Beta ist.