Gemini API CLI

Gemini API CLI (gemini-api) – это клиент командной строки без отслеживания состояния и зависимостей, созданный для ИИ-агентов с доступом к оболочке (и доступный для использования из скриптов и непрерывной интеграции). Затем агент может генерировать текст и медиафайлы, анализировать файлы и делегировать задачи управляемым агентам Gemini. Он работает с Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes и любой средой оболочки.

Каждая функция выполняется как стандартная команда оболочки в Interactions API. Выполните те же команды из подпроцесса агента, терминала или конвейера непрерывной интеграции:

# 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

Как выбрать подходящий инструмент Gemini

Используйте gemini-api, когда агенту или скрипту нужно вызвать Gemini напрямую из оболочки, не добавляя код SDK в проект. Используйте SDK и настройку агента для написания кода, когда вы встраиваете Gemini в приложение.

Принцип работы

Необработанные вызовы REST и интерактивные CLI часто вызывают проблемы у агентов кодирования. Медиафайлы Base64 заполняют контекстное окно, интерактивные подсказки блокируют подпроцессы, а устаревшие данные для обучения вызывают галлюцинации.

Надежность gemini-api для агентов обеспечивается четырьмя особенностями:

• Офлайн-поиск схемы. Передайте --usage, чтобы вывести дерево команд (в формате KDL), или --schema, чтобы вывести схему JSON для запросов --body.
• Файлы на диске, пути в stdout. Команды для работы с медиафайлами и расшифровками записывают файлы на диск и выводят только путь к ним, не включая двоичные данные в контекст.
• Пробные запуски и структурированные выходные данные. --dry-run проверяет входные данные, редактирует учетные данные и выполняет предварительный просмотр HTTP-запроса в офлайн-режиме. Чтобы получить машиночитаемый вывод, передайте -o json, -o toon или --jq. Добавьте --agent-mode, чтобы возвращать структурированные ошибки JSON в stderr, и проверьте коды выхода, чтобы обработать сбои. Команды никогда не запрашивают подтверждение, если вы не передаете --interactive.
• Без отслеживания состояния по умолчанию. Команды не сохраняют скрытое локальное состояние. Объединяйте многоэтапные задачи в цепочки, явно указывая --previous-interaction-id, загруженный URI files/<id> или идентификатор фонового взаимодействия.

При использовании -o json команды мультимедиа по-прежнему записывают файл на диск и выводят метаданные в stdout:

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

Начать

Установите CLI, добавьте gemini-api в PATH, задайте GEMINI_API_KEY и добавьте правила использования для агента программирования.

1. Установите двоичный файл

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. Настройте аутентификацию и проверьте ее

Создайте ключ API в Google AI Studio (см. раздел Ключи API). Задайте GEMINI_API_KEY в оболочке и среде дочернего процесса агента:

export GEMINI_API_KEY="YOUR_API_KEY"

На локальной рабочей станции вы можете сохранить ключ в связке ключей ОС (Связка ключей macOS, Linux Secret Service или Менеджер учетных данных Windows). Чтобы сохранить ключ в ~/.config/gemini-api/config.yaml, передайте --no-keyring:

# 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. Добавьте инструкции для агента

Добавьте этот фрагмент в файл AGENTS.md, CLAUDE.md, .cursorrules или системный запрос проекта, чтобы агент знал, как использовать 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`.

Затем отправьте запрос агенту программирования, как обычно.

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.

Команды

Чтобы посмотреть список всех команд, выполните gemini-api --help, а чтобы просмотреть их в интерактивном режиме – gemini-api explore.

Рабочие процессы

Для каждой команды по умолчанию используется модель, подходящая для ее задачи. Передайте --model (-m), чтобы выбрать другую модель. Чтобы посмотреть доступные варианты, выполните команду gemini-api models.

Генерирование и редактирование изображений

Агенты, создающие веб- или мобильные интерфейсы, могут генерировать плейсхолдеры, значки и главные изображения с помощью Nano Banana. Чтобы изменить изображение, передайте сгенерированный путь обратно в -i:

# 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

Чтобы объединить референсные изображения, например персонажа и руководство по стилю, передайте -i несколько раз.

Синтез речи

gemini-api tts синтезирует аудио в формате WAV с частотой 24 кГц для подсказок в интерфейсе, предварительного прослушивания специальных возможностей и пошаговых руководств с голосовым сопровождением. По умолчанию используется голос Kore. Чтобы выбрать другой, используйте --voice. Для диалога двух говорящих пометьте каждую реплику в запросе и сопоставьте говорящих с голосами:

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

Музыка и видео

Создавайте оригинальные треки с помощью Lyria и генерируйте MP4-клипы с помощью 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

По умолчанию команда video ожидает завершения генерации и записывает MP4-файл на диск. Передайте --async, чтобы сразу получить идентификатор взаимодействия, а затем выполните gemini-api video --resume <id> --out <path>. Передайте -i, чтобы анимировать существующее изображение.

Создание текста

gemini-api generate streams text to stdout:

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

Добавьте --stdin, чтобы вставить текст в запрос. Передайте --previous-interaction-id, чтобы продолжить предыдущее взаимодействие.

Анализ и расшифровка документов

analyze отвечает на вопросы о PDF-файлах, таблицах, скриншотах, аудио- и видеофайлах, а также общедоступных URL YouTube. transcribe записывает отформатированную расшифровку (md, text, json или srt) на диск:

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

Передайте -i в analyze несколько раз, чтобы сравнить файлы, например скриншоты до и после.

gemini-api отправляет локальные файлы размером до 14 МБ (20 МБ после кодирования base64). Для более крупных файлов загрузите один раз с помощью files upload --wait и повторно используйте возвращенный URI 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

Как запускать агентов и управлять ими

Ваш агент программирования может делегировать многоэтапные исследовательские или изолированные задачи управляемым агентам Gemini, например агенту Deep Research. Чтобы сразу получить идентификатор взаимодействия, а не держать поток открытым, передайте --background --stream=false:

# 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

Чтобы остановить выполняющееся задание, запустите gemini-api agent cancel <id>. Вы также можете запустить агента Antigravity в удаленной тестовой среде с помощью agent run или управлять пользовательскими агентами с помощью agent create, list, get и delete. Чтобы настроить изолированные среды агентов, перейдите в раздел Среды.

Специальные тела запросов

Для параметров без специальных флагов передайте необработанные полезные данные JSON Interactions API с помощью --body (встроенные или как @file.json). Передайте --body, чтобы задать схемы response_format, инструменты вызова функций, generation_config или "store": false. Сначала выполните команду gemini-api <command> --schema, чтобы проверить допустимые поля:

# 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 объединяется с флагами команд. Если в обоих файлах задан один и тот же ключ, команда завершается сбоем с кодом выхода 2, чтобы конфликтующие входные данные быстро обнаруживались.

Коды выхода

Каждая команда возвращает типизированный код выхода, поэтому скрипты и агенты могут обрабатывать сбои без синтаксического анализа текста ошибки. Например, 3 указывает на проблему с аутентификацией, а 2 – на недопустимый синтаксис команды.

Выполните команду gemini-api --help-global, чтобы получить список глобальных флагов, общих для всех команд (аутентификация, вывод, сеть и диагностика).

Ограничения

• Для команд потоковой передачи (generate и agent run) требуется --stream=false, если они используются вместе с -o json или --jq, чтобы возвращать один объект ответа JSON.
• Максимальный размер встроенных файлов -i составляет 14 МБ (20 МБ полезной нагрузки запроса, включая кодировку base64). Загружайте большие файлы с помощью gemini-api files upload. Files API удаляет загруженные файлы через 48 часов.
• gemini-api поддерживает стандартные HTTP-запросы, потоковую передачу SSE и асинхронный опрос, но не двунаправленные веб-сокеты. Для потоковой передачи голоса и видео в реальном времени используйте Live API с Google GenAI SDK.

Дальнейшие действия

• Настройка агента-программиста
• Interactions API
• Управляемые агенты Gemini
• gemini-api-cli на GitHub