Gemini API CLI

Gemini API CLI (gemini-api) është një klient i rreshtit të komandave pa gjendje dhe pa varësi, i krijuar për agjentët e IA-së me qasje në shell (dhe i përdorshëm nga skriptet dhe CI). Më pas, agjenti yt i kodimit mund të gjenerojë tekst dhe media, të analizojë skedarë dhe t'u delegojë detyra agjentëve të menaxhuar nga Gemini. Ai funksionon me Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes ose çdo mjedis shell.

Çdo veçori ekzekutohet si një komandë standarde e shell në Interactions API. Ekzekuto të njëjtat komanda nga një nënproces agjenti, terminali yt ose një kanal 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

Zgjidh veglën e duhur të Gemini

Përdor gemini-api kur një agjent ose skript duhet të telefonojë Gemini drejtpërdrejt nga shell pa shtuar kodin SDK në projektin tënd. Përdor SDK-të dhe konfigurimin e agjentit të kodimit kur je duke ndërtuar Gemini në një aplikacion:

Si funksionon

Thirrjet e papërpunuara REST dhe CLI-të ndërvepruese shpesh shkaktojnë probleme për agjentët e kodimit. Base64 media fills the context window, interactive prompts block subprocesses, and stale training data causes hallucinated flags.

Katër zgjedhje të dizajnit e mbajnë gemini-api të besueshme për agjentët:

• Kërkimi i skemës offline: Kalo --usage për të printuar strukturën e komandave (në KDL) ose --schema për të printuar skemën JSON për kërkesat e --body.
• Skedarët në disk, shtigjet në stdout: Komandat e medias dhe transkriptimit shkruajnë skedarë në disk dhe printojnë vetëm shtegun e daljes, duke i mbajtur të dhënat binare jashtë kontekstit.
• Ekzekutimet provë dhe rezultati i strukturuar: --dry-run verifikon hyrjet, redakton kredencialet dhe shfaq paraprakisht kërkesën HTTP offline. Kalo -o json, -o toon, ose --jq për rezultatin e lexueshëm nga makineria. Shto --agent-mode për të kthyer gabimet e strukturuara JSON në stderr dhe kontrollo kodet e daljes për të administruar dështimet. Komandat mos kërko asnjëherë përveçse nëse kalon --interactive.
• Pa gjendje si parazgjedhje: Komandat nuk mbajnë asnjë gjendje lokale të fshehur. Zinxhir puna me shumë hapa në mënyrë eksplicite me --previous-interaction-id, një files/<id> URI e ngarkuar ose një ID ndërveprimi në sfond.

Me -o json, komandat e medias vazhdojnë ta shkruajnë skedarin në disk dhe të printojnë metadatat në stdout:

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

Fillo

Instalo CLI, vendos gemini-api në PATH, cakto GEMINI_API_KEY dhe shto rregulla të përdorimit për agjentin tënd të kodimit.

1. Instalo binarin

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. Konfiguro vërtetimin dhe verifiko

Krijo një çelës API në Google AI Studio (shiko çelësat API). Cakto GEMINI_API_KEY në shell-in tënd dhe mjedisin e nënprocesit të agjentit tënd:

export GEMINI_API_KEY="YOUR_API_KEY"

Në një stacion pune lokal, mund ta ruash çelësin në listën e çelësave të sistemit operativ (macOS Keychain, Linux Secret Service ose Windows Credential Manager). Kalo --no-keyring për ta ruajtur çelësin në ~/.config/gemini-api/config.yaml më mirë:

# 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. Jepi udhëzime agjentit tënd

Shtoje këtë fragment në AGENTS.md, CLAUDE.md, .cursorrules ose kërkesën e sistemit të projektit tënd në mënyrë që agjenti yt i kodimit të dijë se si të përdorë 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`.

Më pas jepi komanda agjentit tënd të kodimit si zakonisht:

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.

Komandat

Ekzekuto gemini-api --help për të listuar të gjitha komandat ose gemini-api explore për t'i shfletuar ato në mënyrë ndërvepruese.

Workflows

Çdo komandë ka si parazgjedhje një model të përshtatshëm për detyrën e saj. Kalo --model (-m) për të zgjedhur një model tjetër. Ekzekuto gemini-api models për të listuar opsionet e disponueshme.

Gjenerimi dhe modifikimi i imazheve

Agjentët që ndërtojnë ndërfaqe përdoruesi për ueb ose për celular mund të gjenerojnë mbajtëse vendesh, ikona dhe imazhe kryesore me Nano Banana. Kalo përsëri një shteg të gjeneruar me -i për të modifikuar imazhin:

# 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

Kalo -i disa herë për të kombinuar imazhet referencë, si p.sh. një personazh dhe një udhëzues stili.

Sinteza e ligjërimit

gemini-api tts sintetizon audion WAV 24 kHz për sinjalet e ndërfaqes së përdoruesit, pamjet paraprake të qasshmërisë dhe udhëzimet e rrëfyera. Zëri i parazgjedhur është Kore; zgjidh një tjetër me --voice. Për dialogun me dy folës, etiketo çdo radhë në kërkesë dhe lidh folësit me zërat:

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

Muzikë dhe video

Kompozo pjesë muzikore origjinale me Lyria dhe gjenero klipe MP4 me 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

Si parazgjedhje, komanda video pret që gjenerimi të përfundojë dhe e shkruan skedarin MP4 në disk. Kalo --async për të kthyer menjëherë një ID ndërveprimi, më pas ekzekuto gemini-api video --resume <id> --out <path> më vonë. Kalo -i për të animuar një imazh ekzistues.

Gjenerimi i tekstit

gemini-api generate transmeton tekstin te stdout:

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

Shto --stdin për të transferuar tekstin në kërkesë. Kalo --previous-interaction-id për të vazhduar një ndërveprim të mëparshëm.

Analiza dhe transkriptimi i dokumenteve

analyze u përgjigjet pyetjeve për skedarët PDF, fletëllogaritëset, pamjet e ekranit, skedarët audio dhe video, si dhe URL-të publike të YouTube. transcribe shkruan një transkript të formatuar (md, text, json ose srt) në 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

Kalo -i disa herë te analyze për të krahasuar skedarët, si p.sh. pamjet e ekranit para dhe pas.

gemini-api dërgon skedarë lokalë të integruar deri në 14 MB (20 MB pas enkodimit base64). Për skedarë më të mëdhenj, ngarko një herë me files upload --wait dhe ripërdor URI-në e kthyer files/<id>:

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

Ekzekuto dhe menaxho agjentët

Agjenti yt i kodimit mund të delegon kërkime me shumë hapa ose detyra të mbyllura në agjentët e menaxhuar nga Gemini, si p.sh. agjenti i Deep Research. Kalo --background --stream=false për të marrë menjëherë një ID ndërveprimi në vend që të mbash hapur një transmetim:

# 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

Ekzekuto gemini-api agent cancel <id> për të ndaluar një punë në ekzekutim. Mund të nisësh gjithashtu agjentin e Antigravity në një hapësirë të kufizuar në distancë me agent run ose të menaxhosh agjentët e personalizuar me agent create, list, get dhe delete. Shiko Mjediset për të konfiguruar hapësirat e kufizuara të agjentëve.

Trupat e personalizuar të kërkesave

Për opsionet pa flamuj të dedikuar, kalo një ngarkesë JSON të papërpunuar të Interactions API me --body (në linjë ose si @file.json). Kalo --body për të caktuar skemat e response_format, veglat e thirrjes së funksionit, generation_config ose "store": false. Ekzekuto gemini-api <command> --schema në fillim për të kontrolluar fushat e vlefshme:

# 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 bashkohet me flamujt e komandës. Nëse të dyja caktojnë të njëjtin çelës, komanda dështon me kodin e daljes 2, kështu që hyrjet në konflikt dështojnë shpejt.

Kodet e daljes

Çdo komandë kthen një kod daljeje të shtypur në mënyrë që skriptet dhe agjentët të mund të menaxhojnë dështimet pa analizuar tekstin e gabimit. Për shembull, 3 sinjalizon një problem vërtetimi dhe 2 sinjalizon sintaksë të pavlefshme komande:

Ekzekuto gemini-api --help-global për të listuar flamujt globalë të ndarë nga çdo komandë (vërtetimi, dalja, rrjeti dhe diagnostikimi).

Kufizimet

• Komandat e transmetimit (generate dhe agent run) kërkojnë --stream=false kur kombinohen me -o json ose --jq për të kthyer një objekt të vetëm përgjigjeje JSON.
• Hyrjet e skedarëve të integruar -i kufizohen në 14 MB të dhëna të skedarëve të papërpunuar (ngarkesa e kërkesës 20 MB duke përfshirë enkodimin base64). Ngarko skedarë të mëdhenj me gemini-api files upload. Files API i fshin skedarët e ngarkuar pas 48 orësh.
• gemini-api mbështet kërkesat standarde HTTP, transmetimin SSE dhe anketimin asinkron, jo WebSockets dydrejtimëshe. Për transmetimin e zërit dhe videos në kohë reale, përdor Live API me Google GenAI SDK.

Çfarë ka më pas

• Konfigurimi i agjentit të kodimit
• Interactions API
• Agjentët e menaxhuar të Gemini
• gemini-api-cli në GitHub