Gemini API CLI вышла в бета-версии: что умеет и как запустить
Google выпустила beta-версию gemini-api — stateless CLI для вызова моделей и управляемых агентов Gemini из shell, скриптов и CI. Разбираем отличие от интерактивного Gemini CLI, установку, dry run и ограничения.
27 октября 2026 года Google добавила Gemini API CLI с командой gemini-api в журнал обновлений Gemini API. Статус инструмента — beta, а не общедоступная стабильная версия. Google описывает его как stateless-клиент командной строки без проектных зависимостей: он вызывает Gemini через Interactions API из терминала, скрипта, CI-задачи или подпроцесса другого агента. Дата обновления справки 28 октября не заменяет дату события: выпуск указан отдельной записью за 27 октября.
Gemini API CLI не следует путать с интерактивным @google/gemini-cli, который Google представила 25 июня 2025 года как open-source ИИ-агента для программирования, решения задач и управления работой в терминале. Новый gemini-api сам по себе не является агентом программирования: он даёт существующему агенту или сценарию стандартные shell-команды для генерации текста и медиа, анализа файлов и запуска управляемых агентов Gemini. Для более широкого цикла разработки — постановки задачи, небольшого патча и тестов — пригодится материал про ИИ для работы с кодом.
Для каких задач подходит gemini-api
Главный сценарий — прямой вызов Gemini из shell без добавления SDK в проект. Команда generate возвращает текст, analyze принимает PDF, изображения, аудио, видео, CSV и текстовые файлы, а медиа-команды записывают результат на диск и печатают путь. Для автоматизации важны машинные форматы вывода JSON и TOON, фильтрация через --jq, режим --agent-mode со структурированными ошибками и отдельные коды завершения.
Инструмент stateless по замыслу: между вызовами он не хранит скрытое локальное состояние беседы. Если нужен следующий шаг, сценарий явно передаёт previous interaction ID, URI загруженного файла или идентификатор фонового задания. При этом Interactions API по умолчанию хранит взаимодействия на стороне сервера; для запроса без такого сохранения документация предусматривает store=false. Файлы имеют отдельный срок хранения. Для собственного приложения, фонового сервиса или Live API Google рекомендует SDK, а не оболочку командной строки.
Установка и проверка без сетевого запроса
Документация предлагает установочный сценарий для macOS и Linux, PowerShell-команду для Windows, установку через Go и готовые архивы релизов. Для автоматизированной среды безопаснее не брать latest при каждой сборке, а закрепить конкретный release tag или версионный архив. Это особенно важно в beta: Google прямо предупреждает о возможных несовместимых изменениях между минорными версиями.
После установки нужен ключ Gemini API. На рабочей станции его можно передать через GEMINI_API_KEY или сохранить в системном хранилище с командой configure. В CI ключ следует получать из хранилища секретов, а не записывать в репозиторий, Dockerfile или журнал сборки. Первый полезный шаг — gemini-api whoami, затем локальный dry run: gemini-api generate "Ответь одним словом: готово" --dry-run. По документации --dry-run проверяет входные параметры, скрывает учётные данные и показывает будущий HTTP-запрос без сетевого вызова.
Dry run проверяет форму команды, а не качество будущего ответа модели. Он не подтверждает доступность выбранной модели, сетевой маршрут, лимит проекта или корректность содержания. После него выполняйте один небольшой реальный запрос и сохраняйте код завершения, stdout и stderr раздельно. Если API возвращает временную ошибку или ограничение частоты, не запускайте бесконечный цикл: практическую политику повторов разбирает гайд об ошибках 429 и 503.
Практический пример для CI
Представим учебную задачу: в сборке есть файл release-notes.md, и нужно получить короткий черновик списка изменений. Это пример команды, а не проведённый редакцией тест. Сценарий передаёт файл, просит вернуть три пункта и требует единый JSON-объект, чтобы следующий шаг не разбирал свободный текст. Сначала посмотрите схему команды gemini-api generate --schema и сохраните её вывод в файл generate-schema.json. Затем подготовьте запрос и выполните его с --dry-run -o json.
Для реального вызова можно передать содержимое через stdin и запросить полный непотоковый JSON: cat release-notes.md | gemini-api generate "Верни JSON с массивом changes из трёх кратких пунктов. Не добавляй факты, которых нет во входе" --stdin --stream=false -o json. В CI проверяйте код 0, наличие ожидаемого поля и соответствие каждого пункта исходному файлу. Код 1 означает ошибку выполнения или API, код 2 — неверную команду или параметры, код 3 — проблему авторизации. Эти коды позволяют ветвить сборку без поиска слов в сообщении ошибки.
Даже валидный JSON не доказывает истинность значений. Схема контролирует структуру, но каждый пункт всё равно нужно сопоставить с release-notes.md. Если задача требует стабильного объекта для дальнейшей программы, используйте отдельную проверку типов и обязательных полей. Общий принцип отделения синтаксиса от смысла разобран в материале о структурированном JSON от ИИ.
Ограничения beta и работа с файлами
Inline-ввод локального файла ограничен 14 МБ исходных данных и примерно 20 МБ после base64-кодирования запроса. Более крупный файл нужно сначала загрузить через Files API и затем использовать URI вида files/ID. Документация указывает удаление загруженных файлов через 48 часов. Перед отправкой рабочего документа отдельно проверьте политику организации и удалите секреты или персональные данные, которые не нужны задаче.
gemini-api поддерживает обычные HTTP-запросы, SSE-поток и асинхронный опрос, но не двунаправленный WebSocket. Для голосового или видеодиалога в реальном времени нужен Live API и SDK. При -o json или --jq потоковые команды generate и agent run требуют --stream=false, иначе вместо одного готового объекта приложение получит последовательность событий. Сборку потокового результата и проверку терминального события подробно объясняет статья о потоковых ответах API ИИ.
Что проверить перед рабочим использованием
Зафиксируйте версию бинарника, источник установки и контрольную сумму архива. Отдельно задайте разрешённые команды, модель, место записи файлов и максимальный размер входа. В CI включите неинтерактивный режим, храните ключ в менеджере секретов, ограничьте права проекта и не выводите переменные окружения в журнал. Для каждого вызова определите ожидаемый формат, допустимый код завершения, дедлайн и способ повторной проверки результата.
Наконец, отделяйте свойства клиента от свойств модели. gemini-api упрощает транспорт и автоматизацию, но не гарантирует качество ответа, доступность любой модели или бесплатное выполнение. Выбор модели и тариф зависят от проекта и актуального каталога Gemini API. Практический маршрут для beta таков: закрепить версию, выполнить dry run, отправить один малый запрос, проверить структуру и смысл, затем только добавлять команду в CI.