CLI Gemini API

Gemini API CLI (gemini-api) adalah klien command line stateless tanpa dependensi yang dibuat untuk agen AI dengan akses shell (dan dapat digunakan dari skrip dan CI). Agen coding Anda kemudian dapat membuat teks dan media, menganalisis file, dan mendelegasikan tugas ke agen terkelola Gemini. Alat ini berfungsi dengan Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes, atau lingkungan shell apa pun.

Setiap fitur berjalan sebagai perintah shell standar di Interactions API. Jalankan perintah yang sama dari subproses agen, terminal, atau 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

Memilih alat Gemini yang tepat

Gunakan gemini-api saat agen atau skrip perlu memanggil Gemini langsung dari shell tanpa menambahkan kode SDK ke project Anda. Gunakan SDK dan penyiapan agen coding saat Anda mem-build Gemini ke dalam aplikasi:

Cara kerjanya

Panggilan REST mentah dan CLI interaktif sering kali menyebabkan masalah bagi agen coding. Media base64 memenuhi jendela konteks, perintah interaktif memblokir subproses, dan data pelatihan yang usang menyebabkan flag halusinasi.

Empat pilihan desain membuat gemini-api tetap andal bagi agen:

• Pencarian skema offline: Teruskan --usage untuk mencetak hierarki perintah (dalam KDL), atau --schema untuk mencetak Skema JSON untuk permintaan --body.
• File di disk, jalur di stdout: Perintah media dan transkripsi menulis file ke disk dan hanya mencetak jalur output, sehingga data biner tidak disertakan dalam konteks.
• Uji coba dan output terstruktur: --dry-run memvalidasi input, menyamarkan kredensial, dan melihat pratinjau permintaan HTTP secara offline. Teruskan -o json, -o toon, atau --jq untuk output yang dapat dibaca mesin. Tambahkan --agent-mode untuk menampilkan error JSON terstruktur di stderr, dan periksa kode keluar untuk menangani kegagalan. Perintah tidak akan pernah meminta kecuali jika Anda meneruskan --interactive.
• Stateless secara default: Perintah tidak menyimpan status lokal tersembunyi. Gabungkan pekerjaan multi-langkah secara eksplisit dengan --previous-interaction-id, URI files/<id> yang diupload, atau ID interaksi latar belakang.

Dengan -o json, perintah media tetap menulis file ke disk dan mencetak metadata ke stdout:

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

Mulai

Instal CLI, tempatkan gemini-api di PATH, tetapkan GEMINI_API_KEY, dan tambahkan aturan penggunaan ke agen coding Anda.

1. Menginstal biner

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. Mengonfigurasi autentikasi dan memverifikasi

Buat kunci API di Google AI Studio (lihat Kunci API). Tetapkan GEMINI_API_KEY di shell dan lingkungan subproses agen Anda:

export GEMINI_API_KEY="YOUR_API_KEY"

Di workstation lokal, Anda dapat menyimpan kunci di keychain OS (macOS Keychain, Linux Secret Service, atau Windows Credential Manager). Teruskan --no-keyring untuk menyimpan kunci di ~/.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. Memberikan petunjuk kepada agen Anda

Tambahkan cuplikan ini ke AGENTS.md, CLAUDE.md, .cursorrules, atau perintah sistem project Anda agar agen coding Anda tahu cara menggunakan 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`.

Kemudian, berikan perintah kepada agen coding Anda seperti biasa:

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.

Perintah

Jalankan gemini-api --help untuk menampilkan semua perintah, atau gemini-api explore untuk menjelajahinya secara interaktif.

Workflows

Setiap perintah ditetapkan secara default ke model yang sesuai untuk tugasnya. Teruskan --model (-m) untuk memilih model yang berbeda. Jalankan gemini-api models untuk menampilkan daftar opsi yang tersedia.

Pembuatan dan pengeditan gambar

Agen yang membangun UI web atau seluler dapat membuat placeholder, ikon, dan banner besar dengan Nano Banana. Teruskan jalur yang dihasilkan kembali dengan -i untuk mengedit gambar:

# 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

Teruskan -i beberapa kali untuk menggabungkan gambar referensi, seperti karakter dan panduan gaya.

Sintesis ucapan

gemini-api tts menyintesis audio WAV 24 kHz untuk isyarat UI, pratinjau aksesibilitas, dan panduan yang dinarasikan. Suara defaultnya adalah Kore; pilih suara lain dengan --voice. Untuk dialog dua pembicara, beri label setiap giliran dalam perintah dan petakan pembicara ke suara:

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

Musik dan video

Buat trek musik orisinal dengan Lyria, dan buat klip MP4 dengan 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

Secara default, perintah video menunggu pembuatan selesai dan menulis file MP4 ke disk. Teruskan --async untuk segera menampilkan ID interaksi, lalu jalankan gemini-api video --resume <id> --out <path> nanti. Teruskan -i untuk menganimasikan gambar yang ada.

Pembuatan teks

gemini-api generate mengalirkan teks ke stdout:

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

Tambahkan --stdin untuk menyalurkan teks ke dalam perintah. Teruskan --previous-interaction-id untuk melanjutkan interaksi sebelumnya.

Analisis dan transkripsi dokumen

analyze menjawab pertanyaan tentang PDF, spreadsheet, screenshot, file audio dan video, serta URL YouTube publik. transcribe menulis transkrip yang diformat (md, text, json, atau srt) ke disk:

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

Teruskan -i beberapa kali ke analyze untuk membandingkan file, seperti screenshot sebelum dan sesudah.

gemini-api mengirimkan file lokal secara inline hingga 14 MB (20 MB setelah encoding base64). Untuk file yang lebih besar, upload sekali dengan files upload --wait dan gunakan kembali URI files/<id> yang ditampilkan:

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

Menjalankan dan mengelola agen

Agen coding Anda dapat mendelegasikan tugas riset atau sandbox multi-langkah ke agen terkelola Gemini, seperti agen Deep Research. Teruskan --background --stream=false untuk segera mendapatkan ID interaksi, bukan membiarkan streaming tetap terbuka:

# 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

Jalankan gemini-api agent cancel <id> untuk menghentikan tugas yang sedang berjalan. Anda juga dapat meluncurkan agen Antigravity di sandbox jarak jauh dengan agent run, atau mengelola agen kustom dengan agent create, list, get, dan delete. Lihat Lingkungan untuk mengonfigurasi sandbox agen.

Isi permintaan kustom

Untuk opsi tanpa flag khusus, teruskan payload JSON Interactions API mentah dengan --body (inline atau sebagai @file.json). Teruskan --body untuk menetapkan skema response_format, alat panggilan fungsi, generation_config, atau "store": false. Jalankan gemini-api <command> --schema terlebih dahulu untuk memeriksa kolom yang valid:

# 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 digabungkan dengan flag perintah. Jika keduanya menetapkan kunci yang sama, perintah akan gagal dengan kode keluar 2 sehingga input yang bertentangan akan gagal dengan cepat.

Kode keluar

Setiap perintah menampilkan kode exit yang diketik sehingga skrip dan agen dapat menangani kegagalan tanpa mengurai teks error. Misalnya, 3 menandakan masalah autentikasi dan 2 menandakan sintaksis perintah yang tidak valid:

Jalankan gemini-api --help-global untuk menampilkan daftar flag global yang digunakan bersama oleh setiap perintah (autentikasi, output, jaringan, dan diagnostik).

Batasan

• Perintah streaming (generate dan agent run) memerlukan --stream=false jika digabungkan dengan -o json atau --jq untuk menampilkan satu objek respons JSON.
• Input file -i inline dibatasi hingga 14 MB data file mentah (payload permintaan 20 MB, termasuk encoding base64). Upload file besar dengan gemini-api files upload. Files API menghapus file yang diupload setelah 48 jam.
• gemini-api mendukung permintaan HTTP standar, streaming SSE, dan polling asinkron, bukan WebSocket dua arah. Untuk streaming suara dan video real-time, gunakan Live API dengan Google GenAI SDK.

Langkah berikutnya

• Penyiapan agen coding
• Interactions API
• Agen terkelola Gemini
• gemini-api-cli di GitHub