Gemini API CLI: Kodlama Ajanınızın Görseller, Videolar, PDF'ler ve Derin Araştırma için Gemini'yi Çağırmasını Sağlayın

Gemini API CLI (gemini-api), Google'ın Gemini API için geliştirdiği açık kaynaklı komut satırı istemcisidir ve Claude Code, Codex, Cursor ile Antigravity gibi kodlama ajanları için tasarlanmıştır. Tek bir Go binary'si kurun, GEMINI_API_KEY değişkenini ayarlayın; ajanınız görsel, video, konuşma ve müzik üretebilir, PDF'leri ve kayıtları analiz edebilir, sesi SRT'ye dönüştürebilir ve Deep Research'i arka planda başlatabilir.

Aşağıda: kurulum, kimlik doğrulama, ajanınızın çalıştıracağı komutlar, Gemini CLI'dan farkı ve Apidog CLI ile nasıl eşleştirileceği yer alıyor. Tüm bayraklar, 30 Ekim 2026'da yayımlanan 0.4.5 sürümündeki gemini-api --help çıktısından kopyalanmıştır.

Gemini API CLI nedir?

Gemini API CLI, Google'ın Interactions API'si için durumsuz, tek binary'den oluşan bir istemcidir. Her komut tek bir HTTP çağrısıdır: bir istem girer, karşılığında bir dosya yolu, transkript, analiz veya etkileşim kimliği çıkar. Mevcut ajanınızın, bir görev Gemini gerektirdiğinde çağırdığı bir araçtır.

Google'ın resmî dokümantasyon sayfası bunu "Interactions API ile birlikte gelişen, açık kaynaklı bir beta sürümü" olarak adlandırıyor. Kod, Apache 2.0 lisansı altında google-gemini/gemini-api-cli adresinde bulunuyor ve macOS, Linux ile Windows üzerinde çalışıyor.

0.4.5 sürümünde gemini-api --help çıktısının listeledikleri ve her komutun varsayılan modeli şöyle:

Gemini API CLI ile Gemini CLI karşılaştırması

İsimler birbirine yakın, işte ayrım. Gemini CLI (@google/gemini-cli) etkileşimli bir kodlama ajanıdır; sohbet ettiğiniz bir Claude Code alternatifi. Gemini API CLI (gemini-api) ise hiçbir ajan döngüsüne sahip değil. Başka bir ajanın çalıştırdığı bir araç.

Claude Code veya Codex içinde çalışıyor ve Gemini'nin medya ile araştırma modellerini bu iş akışının içinde istiyorsanız gemini-api kullanın. Bu, OpenAI CLI ile aynı desendir; yalnızca Google'a yönlendirilmiştir.

Gemini API CLI nasıl kurulur

README'deki dört yoldan birini seçin.

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

Hazır binary'ler: platformunuz için arşivi GitHub Releases üzerinden indirin, checksums.txt ile doğrulayın ve gemini-api'yi PATH değişkeninize ekleyin. Biz Darwin_arm64 arşivini kullandık; shasum -a 256 -c checksums.txt --ignore-missing komutu OK yazdırdı.

Google, küçük sürümler arasında geriye dönük uyumsuz değişikliklerin gelebileceği konusunda uyarıyor; bu yüzden CI'da belirli bir sürümü sabitleyin. Dokümantasyon, kurulum betiğini bash ifadesinden önce yerleştirilmiş GEMINI_VERSION=<release-tag> ile gösteriyor.

Kurulumu doğrulayın:

gemini-api version
# gemini-api 0.4.5

Gemini API CLI kimlik doğrulaması

Google AI Studio'da bir anahtar oluşturun (ücretsiz Gemini API anahtarı alma rehberimiz bunu adım adım anlatıyor), ardından dışa aktarın:

export GEMINI_API_KEY="YOUR_API_KEY"

Kendi çalışma istasyonunuzda ise anahtarı saklayabilirsiniz:

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

configure anahtarı işletim sisteminizin anahtarlığına kaydeder (macOS Keychain, Linux Secret Service veya Windows Credential Manager). Bunun yerine ~/.config/gemini-api/config.yaml içinde tutmak için global --no-keyring bayrağını ekleyin. whoami hangi kimlik bilgisinin etkin olduğunu ve nereden geldiğini gösterir.

Anahtar ayarlanmamışsa gemini-api --help, doğrudan ajanın kendisine hitaben bir satır yazdırır: API anahtarı "kullanıcı tarafından Google AI Studio'da manuel olarak oluşturulmalıdır. Durun ve kullanıcıdan bir anahtar oluşturmasını isteyin". Ajanınız kendi başına bir anahtar yapılandırmak yerine size soracaktır.

--dry-run ile her çağrıyı önizleyin

--dry-run bayrakları doğrular ve isteği, kimlik bilgileri gizlenmiş hâlde yazdırır; ağ çağrısı yapılmaz ve anahtarlık okunmaz. Anahtar ayarlamadan önce de çalışır; buradaki her örneği bu şekilde kontrol ettik.

İşte arka planda çalışan bir Deep Research işinin gerçek dry run çıktısı:

Her komut https://generativelanguage.googleapis.com/v1beta/interactions adresine POST yapar. Her istek için stdout'ta tek bir JSON nesnesi almak üzere -o json ekleyin; böylece ajan bir token harcamadan önce çıktıyı ayrıştırabilir.

Ajanınızın çalıştıracağı Gemini API CLI komutları

Görsel oluşturma ve düzenleme

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

Medya komutları dosyayı yazar ve yalnızca yolunu yazdırır; böylece ajan bunu $(...) ile yakalar ve üretmeye devam eder. image ayrıca --aspect-ratio ve --image-size (512, 1K, 2K veya 4K) alır. Varsayılan model Nano Banana 2.1'dir; neleri iyi yaptığını görmek için Nano Banana 2.1 API rehberimize bakın.

Video, konuşma ve müzik oluşturma

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 daha uzun sürer, bu yüzden video sizin yerinize yoklar (polling). İşlem tutamacını hemen almak için --async, yoklamayı daha sonra kaldığı yerden sürdürmek için --resume <id> kullanın. --resolution varsayılan olarak 720p'dir.

PDF'leri, görselleri ve YouTube URL'lerini analiz etme

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 birden çok kez kullanılabilir ve yerel bir yol, bir files/<id> URI'si veya bir YouTube URL'si kabul eder. Satır içi girdiler ham olarak yaklaşık 14 MB ile sınırlıdır. Daha büyük dosyalar için bir kez yükleyin ve URI'yi yeniden kullanın:

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"

Yüklenen dosyalar 48 saat sonra silinir.

Ses ve videoyu metne dökme

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

--format seçeneği md (varsayılan), text, json veya srt alır. Çıktıdan konuşmacıları ya da zaman damgalarını kaldırmak için --no-speakers veya --no-timestamps ekleyin.

Deep Research'i arka planda çalıştırma

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, bir akışı açık tutmak yerine hemen bir etkileşim kimliği döndürür. Ajan kimliği saklar, başka bir işle ilgilenir ve agent status ile tekrar kontrol eder. agent cancel bir çalıştırmayı durdurur. 0.4.5 yardım çıktısı ayrıca yönetilen ajanlar olarak deep-research-max-preview-04-2026 ve antigravity-preview-05-2026 sürümlerini listeler.

gemini-api'yi ajanlar için güvenli kılan bayraklar

Bunlar, ajanınızın talimatlarına koymaya değer global bayraklardır ve tümü gemini-api --help-global çıktısından alınmıştır:

• --agent-mode (veya GEMINI_CLI_AGENT_MODE=1): stderr'de yapılandırılmış JSON hataları, stdout'ta kompakt TOON çıktısı.
• -o, --output-format: pretty, json, yaml, table veya toon.
• -q, --jq: çıktıyı satır içi filtreler, örneğin --jq '.id'.
• --no-interactive: istem (prompt) veya TUI formu yok; başsız (headless) bir ajanın ihtiyaç duyduğu şey.
• --usage: tam komut ağacını makine tarafından okunabilir KDL olarak verir.
• --schema (komut başına): bir --body yükü için JSON Schema.

Çıkış kodları, metni ayrıştırmaya gerek kalmadan ajana neyin yanlış gittiğini söyler: 0 sorun yok, 1 çalışma zamanı veya API hatası, 2 kullanım ya da doğrulama hatası, 3 kimlik doğrulama. Bir uyarı: akış (streaming) komutlarında (generate, agent run), -o json veya --jq ile tek bir ayrıştırılabilir sonuç almak için --stream=false gerekir.

Kodlama ajanınıza Gemini API CLI'yı verin

Google'ın README'si, AGENTS.md, CLAUDE.md veya .cursorrules dosyalarına yapıştırılacak bir blok sunuyor. Kısaltılmış hâli:

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.

GEMINI_API_KEY değişkeninin ajanın alt süreç ortamına ulaştığından emin olun. Ardından her zamanki gibi istem verin: "Açılış sayfasını oluştur, maskot görseli ve 20 saniyelik bir seslendirme için Gemini'yi kullan ve rakip ürünler üzerine bir Deep Research çalıştırması başlat." Komutları ajan seçer.

Yapmadığı şeyler: gerçek zamanlı ses veya video. WebSocket desteği yok, bu yüzden Live API hâlâ GenAI SDK'larını gerektiriyor.

Geliştirdiğiniz API'yi Apidog CLI ile test edin

gemini-api, ajanınıza Gemini'nin modellerini kazandırır. Ancak sizin API'niz hakkında hiçbir şey bilmez: uygulamanızın Gemini'nin etrafını sardığı /summarize veya /thumbnail uç noktası, ortamları ya da bir sürümün bir şeyi bozmadığını kanıtlayan doğrulamalar. Bu, Apidog CLI'nın işidir ve aynı ajan ikisini de çalıştırabilir.

Bir kez kurun:

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

Sonra ajanınıza tek bir istem verin:

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.

Ajan, Gemini'nin yanıtını gemini-api ile kontrol eder; ardından bir yük (payload) yazmadan önce Apidog şemasını okur, doğrular ve test senaryosunu oluşturup çalıştırır:

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 bir tuzağa dikkat çekiyor: senaryonun geçerli bir categoryId değerine ihtiyacı var, bu yüzden önce apidog test-case category --project <id> ile kategorileri listeleyin. -r cli,json yerine -r junit yazın; aynı satır CI'da çalışır. Ajanınız Claude Code ise Claude Code içinde Apidog CLI ile başlayın. Apidog'un Ücretsiz planı 4 kullanıcıya kadar destekler.

SSS

Gemini API CLI ücretsiz mi? CLI'nin kendisi Apache 2.0 altında ücretsiz ve açık kaynaklıdır. Her çağrı, normal Gemini API fiyatlandırması kapsamında API anahtarınıza faturalandırılır. Ücretsiz katmanın neleri kapsadığını Gemini API ücretsiz katman rehberimizde görebilirsiniz.

gemini-api, Gemini CLI ile aynı şey mi? Hayır. Gemini CLI etkileşimli bir kodlama ajanıdır. gemini-api ise diğer ajanların, betiklerin ve CI işlerinin Gemini modellerine ve yönetilen ajanlara ulaşmak için çağırdığı durumsuz bir araçtır.

Komutları API anahtarı olmadan test edebilir miyim? Evet. --dry-run komutu doğrular ve tam isteği, ağ çağrısı yapmadan ve anahtarlık okumadan yazdırır. Bu yazıdaki her örnek 0.4.5 sürümünde bu şekilde kontrol edildi.

14 MB'dan büyük dosyalarla nasıl başa çıkarım? gemini-api files upload <file> --wait komutunu çalıştırın, döndürülen files/<id> değerini saklayın ve analyze, transcribe, generate, image, video veya agent run komutlarında -i seçeneğine verin. Yüklemeler 48 saat sonra sona erer.

Sürümü sabitlemeli miyim? Evet, CI'da sabitleyin. Google, CLI beta aşamasındayken küçük sürümler arasında geriye dönük uyumsuz değişiklikler olabileceğini söylüyor.