Gemini API CLI: Biarkan Agen Coding Anda Memanggil Gemini untuk Gambar, Video, PDF, dan Riset Mendalam

Gemini API CLI (gemini-api) adalah klien baris perintah sumber terbuka Google untuk Gemini API, yang dibangun untuk agen pengkodean seperti Claude Code, Codex, Cursor, dan Antigravity. Pasang satu biner Go, setel GEMINI_API_KEY, dan agen Anda dapat menghasilkan gambar, video, ucapan, dan musik, menganalisis PDF dan rekaman, mentranskripsikan audio ke SRT, dan menjalankan Deep Research di latar belakang.

Di bawah ini: instalasi, autentikasi, perintah yang akan dijalankan agen Anda, perbedaannya dari Gemini CLI, dan cara memadukannya dengan Apidog CLI. Setiap flag disalin dari gemini-api --help pada versi 0.4.5, dirilis 30 Oktober 2026.

Apa itu Gemini API CLI?

Gemini API CLI adalah klien tanpa status, biner tunggal untuk Interactions API Google. Setiap perintah adalah satu panggilan HTTP: prompt masuk, dan jalur file, transkrip, analisis, atau ID interaksi keluar. Ini adalah alat yang dipanggil agen Anda yang sudah ada ketika suatu tugas membutuhkan Gemini.

Halaman dokumentasi resmi Google menyebutnya “rilis beta sumber terbuka yang berkembang seiring dengan Interactions API.” Kode tersedia di google-gemini/gemini-api-cli di bawah Apache 2.0, dan berjalan di macOS, Linux, dan Windows.

Berikut adalah apa yang tercantum dalam gemini-api --help pada 0.4.5, dengan model default untuk setiap perintah:

Gemini API CLI vs Gemini CLI

Namanya mirip, jadi inilah perbedaannya. Gemini CLI (@google/gemini-cli) adalah agen pengkodean interaktif, alternatif Claude Code yang Anda ajak mengobrol. Gemini API CLI (gemini-api) tidak memiliki loop agen sama sekali. Ini adalah alat yang dijalankan oleh agen lain.

Jika Anda bekerja di Claude Code atau Codex dan menginginkan model media dan riset Gemini di dalam alur kerja tersebut, gunakan gemini-api. Polanya sama seperti OpenAI CLI, yang diarahkan ke Google.

Cara menginstal Gemini API CLI

Pilih salah satu dari empat rute dari README.

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

Biner siap pakai: unduh arsip untuk platform Anda dari GitHub Releases, periksa dengan checksums.txt, dan letakkan gemini-api di PATH Anda. Kami menggunakan arsip Darwin_arm64; shasum -a 256 -c checksums.txt --ignore-missing mencetak OK.

Google memperingatkan bahwa perubahan yang merusak dapat terjadi antar versi minor, jadi pin rilis di CI. Dokumentasi menunjukkan skrip instalasi dengan GEMINI_VERSION=<release-tag> ditempatkan sebelum bash.

Konfirmasi instalasi:

gemini-api version
# gemini-api 0.4.5

Autentikasi Gemini API CLI

Buat kunci di Google AI Studio (panduan kami untuk mendapatkan kunci Gemini API gratis membahasnya), lalu ekspor:

export GEMINI_API_KEY="YOUR_API_KEY"

Di workstation Anda sendiri, Anda dapat menyimpannya sebagai gantinya:

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

configure menyimpan kunci ke keychain OS Anda (macOS Keychain, Linux Secret Service, atau Windows Credential Manager). Tambahkan flag global --no-keyring untuk menyimpannya di ~/.config/gemini-api/config.yaml sebagai gantinya. whoami menunjukkan kredensial mana yang aktif dan dari mana asalnya.

Jika tidak ada kunci yang disetel, gemini-api --help mencetak baris yang ditujukan kepada agen itu sendiri: kunci API “harus dibuat secara manual oleh pengguna di Google AI Studio. Berhenti dan minta pengguna membuatnya”. Agen Anda akan bertanya kepada Anda daripada mengonfigurasi kunci sendiri.

Pratinjau setiap panggilan dengan --dry-run

--dry-run memvalidasi flag dan mencetak permintaan dengan kredensial yang disunting, tanpa panggilan jaringan dan tanpa pembacaan keychain. Ini berfungsi sebelum Anda menyetel kunci, yang merupakan cara kami memeriksa setiap contoh di sini.

Berikut adalah dry run nyata dari pekerjaan Deep Research latar belakang:

Setiap perintah mengirim POST ke https://generativelanguage.googleapis.com/v1beta/interactions. Tambahkan -o json untuk mendapatkan satu objek JSON per permintaan di stdout, yang dapat diurai oleh agen sebelum menghabiskan token.

Perintah Gemini API CLI yang akan dijalankan agen Anda

Hasilkan dan edit gambar

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

Perintah media menulis file dan hanya mencetak jalurnya, sehingga agen menangkapnya dengan $(...) dan terus membangun. image juga menerima --aspect-ratio dan --image-size (512, 1K, 2K, atau 4K). Model defaultnya adalah Nano Banana 2.1; lihat panduan API Nano Banana 2.1 kami untuk keunggulannya.

Hasilkan video, ucapan, dan musik

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 membutuhkan waktu lebih lama, jadi video melakukan polling untuk Anda. Gunakan --async untuk mendapatkan handle operasi segera dan --resume <id> untuk melanjutkan polling nanti. --resolution defaultnya 720p.

Analisis PDF, gambar, dan URL 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 dapat diulang dan menerima jalur lokal, URI files/<id>, atau URL YouTube. Input inline dibatasi sekitar 14 MB mentah. Untuk file yang lebih besar, unggah sekali dan gunakan kembali URI-nya:

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"

File yang diunggah dihapus setelah 48 jam.

Transkripsikan audio dan video

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

--format menerima md (default), text, json, atau srt. Tambahkan --no-speakers atau --no-timestamps untuk menghilangkan salah satunya dari output.

Jalankan Deep Research di latar belakang

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 mengembalikan ID interaksi sekaligus alih-alih menahan aliran tetap terbuka. Agen menyimpan ID, mengerjakan hal lain, dan memeriksa kembali dengan agent status. agent cancel menghentikan proses. Bantuan 0.4.5 juga mencantumkan deep-research-max-preview-04-2026 dan antigravity-preview-05-2026 sebagai agen terkelola.

Flag yang membuat gemini-api aman untuk agen

Ini adalah flag global yang layak dimasukkan ke dalam instruksi agen Anda, semuanya dari gemini-api --help-global:

• --agent-mode (atau GEMINI_CLI_AGENT_MODE=1): error JSON terstruktur di stderr dan output TOON ringkas di stdout.
• -o, --output-format: pretty, json, yaml, table, atau toon.
• -q, --jq: filter output secara inline, misalnya --jq '.id'.
• --no-interactive: tanpa prompt atau formulir TUI, yang dibutuhkan agen headless.
• --usage: pohon perintah lengkap sebagai KDL yang dapat dibaca mesin.
• --schema (per perintah): JSON Schema untuk payload --body.

Kode keluar memberi tahu agen apa yang salah tanpa mengurai teks: 0 ok, 1 kegagalan runtime atau API, 2 kesalahan penggunaan atau validasi, 3 autentikasi. Satu jebakan: perintah streaming (generate, agent run) memerlukan --stream=false sebelum -o json atau --jq akan memberikan satu hasil yang dapat diurai.

Beri agen pengkodean Anda Gemini API CLI

README Google menyertakan blok untuk ditempel ke AGENTS.md, CLAUDE.md, atau .cursorrules. Dipangkas:

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.

Pastikan GEMINI_API_KEY mencapai lingkungan subproses agen. Lalu beri prompt seperti biasa: “Bangun halaman landing, gunakan Gemini untuk gambar maskot dan voiceover 20 detik, dan mulai proses Deep Research tentang produk pesaing.” Agen memilih perintahnya.

Apa yang tidak dilakukannya: suara atau video real-time. Tidak ada dukungan WebSocket, jadi Live API masih memerlukan GenAI SDK.

Uji API yang Anda bangun dengan Apidog CLI

gemini-api memberi agen Anda model Gemini. Ia tidak tahu apa-apa tentang API Anda sendiri: endpoint /summarize atau /thumbnail yang dibungkus aplikasi Anda di sekitar Gemini, lingkungannya, atau assertion yang membuktikan rilis tidak rusak. Itu tugas Apidog CLI, dan agen yang sama dapat menjalankan keduanya.

Siapkan sekali:

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

Lalu beri agen Anda satu 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.

Agen memeriksa jawaban Gemini dengan gemini-api, lalu membaca skema Apidog sebelum menulis payload, memvalidasinya, dan membuat serta menjalankan kasus:

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 menandai satu jebakan: kasus memerlukan categoryId yang valid, jadi daftarkan dulu dengan apidog test-case category --project <id>. Ganti -r cli,json dengan -r junit dan baris yang sama berjalan di CI. Jika Claude Code adalah agen Anda, mulailah dengan Apidog CLI di Claude Code. Paket Free Apidog mencakup hingga 4 pengguna.

FAQ

Apakah Gemini API CLI gratis? CLI-nya sendiri gratis dan sumber terbuka di bawah Apache 2.0. Setiap panggilan ditagih ke kunci API Anda berdasarkan harga Gemini API normal. Untuk cakupan paket gratis, lihat panduan paket gratis Gemini API kami.

Apakah gemini-api sama dengan Gemini CLI? Tidak. Gemini CLI adalah agen pengkodean interaktif. gemini-api adalah alat tanpa status yang dipanggil oleh agen lain, skrip, dan pekerjaan CI untuk menjangkau model Gemini dan agen terkelola.

Bisakah saya menguji perintah tanpa kunci API? Ya. --dry-run memvalidasi perintah dan mencetak permintaan persisnya tanpa panggilan jaringan dan tanpa pembacaan keychain. Setiap contoh di posting ini diperiksa dengan cara itu pada 0.4.5.

Bagaimana cara menangani file yang lebih besar dari 14 MB? Jalankan gemini-api files upload <file> --wait, simpan files/<id> yang dikembalikan, dan teruskan ke -i pada analyze, transcribe, generate, image, video, atau agent run. Unggahan kedaluwarsa setelah 48 jam.

Haruskah saya pin versi? Ya, di CI. Google mengatakan perubahan yang merusak dapat terjadi antar versi minor selama CLI dalam beta.