Gemini API CLI

Gemini API KSA (gemini-api), kabuk erişimi olan yapay zeka ajanları için tasarlanmış, durum bilgisiz ve bağımlılığı bulunmayan bir komut satırı istemcisidir. Komut dosyalarından ve CI'dan kullanılabilir. Kodlama temsilciniz daha sonra metin ve medya oluşturabilir, dosyaları analiz edebilir ve görevleri Gemini tarafından yönetilen temsilcilere devredebilir. Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes veya herhangi bir kabuk ortamıyla çalışır.

Her özellik, Interactions API'de standart bir kabuk komutu olarak çalışır. Aynı komutları bir temsilci alt işleminden, terminalinizden veya bir CI ardışık düzeninden çalıştırın:

# 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

Doğru Gemini aracını seçme

Bir temsilcinin veya komut dosyasının, projenize SDK kodu eklemeden Gemini'ı doğrudan kabuktan çağırması gerektiğinde gemini-api aracını kullanın. Gemini'ı bir uygulamaya entegre ederken SDK'ları ve kodlama temsilcisi kurulumunu kullanın:

İşleyiş şekli

Ham REST çağrıları ve etkileşimli CLI'lar, kodlama temsilcileri için genellikle sorunlara neden olur. Base64 medya, bağlam penceresini doldurur; etkileşimli istemler, alt süreçleri engeller ve eski eğitim verileri, halüsinasyonlu işaretlere neden olur.

Dört tasarım seçeneği, gemini-api modelinin temsilciler için güvenilir olmasını sağlar:

• Çevrimdışı şema arama: Komut ağacını (KDL biçiminde) yazdırmak için --usage, --body istekleri için JSON şemasını yazdırmak üzere --schema değerini iletin.
• Diskteki dosyalar, stdout üzerindeki yollar: Medya ve transkript komutları, dosyaları diske yazar ve yalnızca çıkış yolunu yazdırarak ikili verileri bağlam dışında tutar.
• Deneme çalıştırmaları ve yapılandırılmış çıkış: --dry-run, girişleri doğrular, kimlik bilgilerini çıkartır ve HTTP isteğini çevrimdışı olarak önizler. Makine tarafından okunabilir çıkış için -o json, -o toon veya --jq parametresini iletin. stderr üzerinde yapılandırılmış JSON hataları döndürmek için --agent-mode ekleyin ve hataları işlemek için çıkış kodlarını kontrol edin. Komutlar, --interactive parametresini iletmediğiniz sürece hiçbir zaman istem göstermez.
• Varsayılan olarak durum bilgisiz: Komutlar gizli yerel durumları saklamaz. --previous-interaction-id, yüklenen bir files/<id> URI'si veya arka plan etkileşim kimliği ile çok adımlı çalışmaları açıkça zincirleyin.

-o json ile medya komutları, dosyayı diske yazmaya ve meta verileri stdout'e yazdırmaya devam eder:

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

Başlayın

CLI'yı yükleyin, gemini-api dosyasını PATH dizinine yerleştirin, GEMINI_API_KEY değişkenini ayarlayın ve kodlama temsilcinize kullanım kuralları ekleyin.

1. İkili programı yükleme

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. Kimlik doğrulamayı yapılandırma ve doğrulama

Google AI Studio'da bir API anahtarı oluşturun (API anahtarları bölümüne bakın). Kabuğunuzda ve temsilcinizin alt işlem ortamında GEMINI_API_KEY değerini ayarlayın:

export GEMINI_API_KEY="YOUR_API_KEY"

Yerel bir iş istasyonunda anahtarı işletim sisteminizin anahtar zincirine (macOS Anahtar Zinciri, Linux Secret Service veya Windows Kimlik Bilgisi Yöneticisi) kaydedebilirsiniz. Anahtarı yerine ~/.config/gemini-api/config.yaml içinde depolamak için --no-keyring parametresini iletin:

# 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. Ajanlarınıza talimat verin

Kodlama temsilcinizin gemini-api aracını nasıl kullanacağını bilmesi için bu snippet'i projenizin AGENTS.md, CLAUDE.md, .cursorrules veya sistem istemine ekleyin:

## 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`.

Ardından, kodlama temsilcinize her zamanki gibi istem girin:

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.

Komutlar

Tüm komutları listelemek için gemini-api --help komutunu, komutlara etkileşimli olarak göz atmak için gemini-api explore komutunu çalıştırın.

İş akışları

Her komut, varsayılan olarak görevine uygun bir model kullanır. Farklı bir model seçmek için --model (-m) parametresini iletin. Kullanılabilir seçenekleri listelemek için gemini-api models komutunu çalıştırın.

Görüntü üretme ve düzenleme

Web veya mobil kullanıcı arayüzleri oluşturan temsilciler, Nano Banana ile yer tutucular, simgeler ve hero resimler oluşturabilir. Resmi düzenlemek için oluşturulan yolu -i ile geri iletin:

# 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

Karakter ve stil kılavuzu gibi referans görselleri birleştirmek için -i parametresini birden fazla kez kullanın.

Konuşma sentezi

gemini-api tts; kullanıcı arayüzü işaretleri, erişilebilirlik önizlemeleri ve sesli açıklamalı adım adım açıklamalar için 24 kHz WAV ses sentezler. Varsayılan ses Kore. --voice ile başka bir ses seçebilirsiniz. İki konuşmacılı diyaloglarda, istemdeki her sırayı etiketleyin ve konuşmacıları seslerle eşleştirin:

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

Müzik ve video

Lyria ile özgün parçalar besteleyin ve Gemini Omni ile MP4 klipler oluşturun:

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

Varsayılan olarak video komutu, oluşturma işleminin tamamlanmasını bekler ve MP4 dosyasını diske yazar. Etkileşim kimliğini hemen döndürmek için --async değerini iletin, ardından gemini-api video --resume <id> --out <path> değerini çalıştırın. Mevcut bir resmi canlandırmak için -i parametresini iletin.

Metin oluşturma

gemini-api generate, stdout numaralı telefona kısa mesaj gönderiyor:

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

Metni isteme aktarmak için --stdin ekleyin. Önceki bir etkileşimi devam ettirmek için --previous-interaction-id parametresini iletin.

Belge analizi ve transkripsiyon

analyze; PDF'ler, e-tablolar, ekran görüntüleri, ses ve video dosyaları ile herkese açık YouTube URL'leri hakkındaki soruları yanıtlar. transcribe, biçimlendirilmiş bir transkripti (md, text, json veya srt) diske yazar:

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

Dosyaları karşılaştırmak için -i parametresini analyze komutuna birden çok kez iletin (ör. öncesi ve sonrası ekran görüntüleri).

gemini-api, 14 MB'a kadar (base64 kodlamasından sonra 20 MB) yerel dosyaları satır içi olarak gönderir. Daha büyük dosyalar için files upload --wait ile bir kez yükleyin ve döndürülen files/<id> URI'sini yeniden kullanın:

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

Temsilcileri çalıştırma ve yönetme

Kodlama temsilciniz, çok adımlı araştırma veya korumalı alan görevlerini Deep Research temsilcisi gibi Gemini tarafından yönetilen temsilcilere devredebilir. Bir akışı açık tutmak yerine hemen etkileşim kimliği almak için --background --stream=false parametresini iletin:

# 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

Çalışan bir işi durdurmak için gemini-api agent cancel <id> komutunu çalıştırın. Ayrıca agent run ile uzak bir korumalı alanda Antigravity ajanını başlatabilir veya agent create, list, get ve delete ile özel ajanları yönetebilirsiniz. Temsilci korumalı alanlarını yapılandırmak için Ortamlar bölümüne bakın.

Özel istek gövdeleri

Özel işaretleri olmayan seçenekler için --body (satır içi veya @file.json olarak) ile ham bir Interactions API JSON yükü iletin. response_format şemalarını, işlev çağrısı araçlarını, generation_config veya "store": false değerini ayarlamak için --body değerini iletin. Geçerli alanları kontrol etmek için önce gemini-api <command> --schema komutunu çalıştırın:

# 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, komut işaretleriyle birleştirilir. Her ikisi de aynı anahtarı ayarlarsa komut, 2 çıkış koduyla başarısız olur. Böylece çakışan girişler hızlı bir şekilde başarısız olur.

Çıkış kodları

Her komut, yazılı bir çıkış kodu döndürür. Böylece komut dosyaları ve aracılar, hata metnini ayrıştırmadan hataları işleyebilir. Örneğin, 3 bir kimlik doğrulama sorununu, 2 ise geçersiz komut söz dizimini belirtir:

Her komutun paylaştığı genel işaretleri (kimlik doğrulama, çıkış, ağ ve teşhis) listelemek için gemini-api --help-global komutunu çalıştırın.

Sınırlamalar

• Akış komutları (generate ve agent run), tek bir JSON yanıt nesnesi döndürmek için -o json veya --jq ile birleştirildiğinde --stream=false gerektirir.
• Satır içi -i dosya girişleri, 14 MB ham dosya verisiyle (Base64 kodlaması dahil 20 MB istek yükü) sınırlıdır. gemini-api files upload ile büyük dosyalar yükleyin. Files API, yüklenen dosyaları 48 saat sonra siler.
• gemini-api; standart HTTP isteklerini, SSE akışını ve eşzamansız yoklamayı destekler ancak çift yönlü WebSockets'i desteklemez. Anlık ses ve video akışı için Google GenAI SDK'ları ile Live API'yi kullanın.

Sırada ne var?

• Kodlama temsilcisi kurulumu
• Interactions API
• Gemini tarafından yönetilen temsilciler
• GitHub'da gemini-api-cli