Gemini API CLI: 코딩 에이전트가 이미지, 동영상, PDF, Deep Research를 위해 Gemini를 호출하도록 하기

Gemini API CLI(gemini-api)는 Claude Code, Codex, Cursor, Antigravity 같은 코딩 에이전트를 위해 만들어진 Google의 오픈소스 Gemini API 명령줄 클라이언트입니다. Go 바이너리 하나를 설치하고 GEMINI_API_KEY를 설정하면, 에이전트가 이미지, 비디오, 음성, 음악을 생성하고, PDF와 녹음을 분석하며, 오디오를 SRT로 전사하고, 백그라운드에서 Deep Research를 실행할 수 있습니다.

지금 Apidog를 사용해 보세요

이 글은 설치, 인증, 에이전트가 실행할 명령, Gemini CLI와의 차이점, 그리고 Apidog CLI와 함께 사용하는 방법을 다룹니다. 모든 플래그는 2026년 10월 30일에 릴리스된 버전 0.4.5의 gemini-api --help에서 그대로 가져왔습니다.

Gemini API CLI란 무엇인가?

Gemini API CLI는 Google의 Interactions API를 위한 상태 비저장(stateless) 단일 바이너리 클라이언트입니다. 각 명령은 하나의 HTTP 호출입니다. 프롬프트가 들어가면 파일 경로, 전사본, 분석 결과 또는 인터랙션 ID가 나옵니다. 작업에 Gemini가 필요할 때 기존 에이전트가 호출하는 도구입니다.

Google의 공식 문서 페이지는 이를 "Interactions API와 함께 발전하는 오픈소스 베타 릴리스"라고 부릅니다. 코드는 Apache 2.0 라이선스로 google-gemini/gemini-api-cli에 있으며, macOS, Linux, Windows에서 실행됩니다.

다음은 0.4.5에서 gemini-api --help가 나열하는 내용과 각 명령의 기본 모델입니다:

그룹	명령	기능	기본 모델
Create	generate	텍스트 및 멀티모달 생성	gemini-3.8-flash
Create	image	이미지 생성 또는 편집	gemini-nano-banana-2.1
Create	video	비디오 생성 및 편집	gemini-omni-1.1-flash
Create	tts / music	음성 및 음악	gemini-3.8-flash-tts / lyria-3.5
Understand	analyze	PDF, 이미지, 오디오, 비디오, YouTube URL에 대한 질문	gemini-3.8-flash
Understand	transcribe	오디오 또는 비디오를 md, text, json 또는 srt로 변환	gemini-3.5-transcribe
Manage	agent	모델 또는 Deep Research 같은 관리형 에이전트 실행	실행별로 설정
Manage	files	Files API 업로드, 48시간 보존	해당 없음

Gemini API CLI vs Gemini CLI

이름이 비슷하니 차이를 정리하겠습니다. Gemini CLI(@google/gemini-cli)는 대화형 코딩 에이전트로, 당신이 대화하는 Claude Code 대안입니다. Gemini API CLI(gemini-api)에는 에이전트 루프가 전혀 없습니다. 다른 에이전트가 실행하는 도구입니다.

	Gemini API CLI	Gemini CLI
바이너리	gemini-api	gemini
역할	에이전트가 호출하는 도구	당신이 대화하는 에이전트
미디어 출력	이미지, 비디오, 음성, 음악을 디스크에 저장	주요 초점 아님
최적 용도	Claude Code, Codex, Cursor에 Gemini 모델 제공	Gemini를 코딩 에이전트로 사용

Claude Code나 Codex에서 작업하며 그 워크플로 안에서 Gemini의 미디어 및 리서치 모델을 원한다면 gemini-api를 사용하세요. Google을 향해 있다는 점만 다를 뿐, OpenAI CLI와 동일한 패턴입니다.

Gemini API CLI 설치 방법

README에 있는 네 가지 방법 중 하나를 선택하세요.

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

사전 빌드된 바이너리: GitHub Releases에서 자신의 플랫폼용 아카이브를 다운로드하고, checksums.txt와 대조한 뒤, gemini-api를 PATH에 넣으세요. 저희는 Darwin_arm64 아카이브를 사용했으며, shasum -a 256 -c checksums.txt --ignore-missing이 OK를 출력했습니다.

Google은 마이너 버전 간에 호환성을 깨는 변경이 발생할 수 있다고 경고하므로, CI에서는 릴리스를 고정(pin)하세요. 문서에서는 설치 스크립트에서 bash 앞에 GEMINI_VERSION=<release-tag>를 두는 방법을 보여줍니다.

설치를 확인하세요:

gemini-api version
# gemini-api 0.4.5

Gemini API CLI 인증

Google AI Studio에서 키를 생성한 다음(무료로 Gemini API 키 받기 가이드에서 자세히 다룹니다), 내보내세요:

export GEMINI_API_KEY="YOUR_API_KEY"

자신의 워크스테이션에서는 대신 저장할 수도 있습니다:

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

configure는 키를 OS 키체인(macOS Keychain, Linux Secret Service 또는 Windows Credential Manager)에 저장합니다. 대신 ~/.config/gemini-api/config.yaml에 보관하려면 전역 --no-keyring 플래그를 추가하세요. whoami는 어떤 자격 증명이 활성 상태인지, 어디에서 왔는지 보여줍니다.

키가 설정되지 않은 경우, gemini-api --help는 에이전트 자체를 향한 문장을 출력합니다. API 키는 "사용자가 Google AI Studio에서 수동으로 생성해야 합니다. 중단하고 사용자에게 생성을 요청하세요."라고 나옵니다. 에이전트는 스스로 키를 구성하지 않고 당신에게 요청할 것입니다.

--dry-run으로 모든 호출 미리보기

--dry-run은 플래그를 검증하고 자격 증명을 가린 상태로 요청을 출력하며, 네트워크 호출도 키체인 읽기도 하지 않습니다. 키를 설정하기 전에도 작동하므로, 여기 있는 모든 예제를 이 방식으로 확인했습니다.

다음은 백그라운드 Deep Research 작업의 실제 dry run입니다:

모든 명령은 https://generativelanguage.googleapis.com/v1beta/interactions로 POST합니다. -o json을 추가하면 요청당 하나의 JSON 객체를 stdout으로 받을 수 있어, 에이전트가 토큰을 소비하기 전에 파싱할 수 있습니다.

에이전트가 실행할 Gemini API CLI 명령

이미지 생성 및 편집

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

미디어 명령은 파일을 쓰고 해당 경로만 출력하므로, 에이전트는 $(...)로 이를 캡처하여 계속 작업을 이어갑니다. image는 --aspect-ratio와 --image-size(512, 1K, 2K 또는 4K)도 받습니다. 기본 모델은 Nano Banana 2.1이며, 이 모델이 잘하는 것은 Nano Banana 2.1 API 가이드를 참고하세요.

비디오, 음성, 음악 생성

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가 대신 폴링합니다. --async를 사용하면 작업 핸들을 즉시 받고, --resume <id>로 나중에 폴링을 다시 시작할 수 있습니다. --resolution의 기본값은 720p입니다.

PDF, 이미지, YouTube URL 분석

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은 반복 지정할 수 있으며, 로컬 경로, files/<id> URI, 또는 YouTube URL을 받습니다. 인라인 입력은 원본 기준 약 14MB로 제한됩니다. 더 큰 파일의 경우 한 번 업로드하고 URI를 재사용하세요:

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"

업로드된 파일은 48시간 후에 삭제됩니다.

오디오 및 비디오 전사

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

--format은 md(기본값), text, json 또는 srt를 받습니다. --no-speakers 또는 --no-timestamps를 추가하면 출력에서 화자나 타임스탬프를 제거할 수 있습니다.

백그라운드에서 Deep Research 실행

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는 스트림을 열어둔 채 유지하는 대신 인터랙션 ID를 즉시 반환합니다. 에이전트는 ID를 저장하고 다른 작업을 하다가 agent status로 다시 확인합니다. agent cancel은 실행을 중지합니다. 0.4.5 도움말에는 deep-research-max-preview-04-2026과 antigravity-preview-05-2026도 관리형 에이전트로 나열되어 있습니다.

gemini-api를 에이전트에 안전하게 만드는 플래그

다음은 에이전트 지침에 넣을 만한 전역 플래그로, 모두 gemini-api --help-global에서 가져온 것입니다:

• --agent-mode(또는 GEMINI_CLI_AGENT_MODE=1): stderr에 구조화된 JSON 오류, stdout에 간결한 TOON 출력.
• -o, --output-format: pretty, json, yaml, table 또는 toon.
• -q, --jq: 출력을 인라인으로 필터링합니다. 예를 들어 --jq '.id'.
• --no-interactive: 프롬프트나 TUI 양식이 없으며, 헤드리스 에이전트에 필요합니다.
• --usage: 전체 명령 트리를 기계 판독 가능한 KDL로 출력.
• --schema(명령별): --body 페이로드에 대한 JSON 스키마.

종료 코드는 텍스트를 파싱하지 않고도 에이전트에게 무엇이 잘못되었는지 알려줍니다. 0은 정상, 1은 런타임 또는 API 실패, 2는 사용법 또는 검증 오류, 3은 인증입니다. 한 가지 주의점이 있습니다. 스트리밍 명령(generate, agent run)은 -o json이나 --jq가 단일 파싱 가능한 결과를 주려면 --stream=false가 필요합니다.

코딩 에이전트에 Gemini API CLI 제공하기

Google의 README에는 AGENTS.md, CLAUDE.md 또는 .cursorrules에 붙여 넣을 블록이 있습니다. 발췌하면 다음과 같습니다:

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가 에이전트의 서브프로세스 환경에 전달되는지 확인하세요. 그런 다음 평소처럼 프롬프트를 입력하세요: "랜딩 페이지를 만들고, 마스코트 이미지와 20초 보이스오버에는 Gemini를 사용하고, 경쟁 제품에 대한 Deep Research 실행을 시작해 줘." 그러면 에이전트가 명령을 선택합니다.

하지 않는 것도 있습니다. 실시간 음성이나 비디오입니다. WebSocket 지원이 없으므로 Live API는 여전히 GenAI SDK가 필요합니다.

Apidog CLI로 직접 만든 API 테스트하기

gemini-api는 에이전트에게 Gemini의 모델을 제공합니다. 하지만 당신의 자체 API — 앱이 Gemini를 감싸는 /summarize나 /thumbnail 엔드포인트, 그 환경, 또는 릴리스가 깨지지 않았음을 입증하는 검증 — 에 대해서는 아무것도 모릅니다. 그것이 Apidog CLI의 일이며, 같은 에이전트가 둘 다 실행할 수 있습니다.

한 번 설정하세요:

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

그런 다음 에이전트에게 하나의 프롬프트를 주세요:

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.

에이전트는 gemini-api로 Gemini의 답변을 확인한 다음, Apidog 스키마를 읽고 페이로드를 작성하며, 이를 검증하고 케이스를 생성하고 실행합니다:

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는 한 가지 함정을 알려줍니다. 케이스에는 유효한 categoryId가 필요하므로, 먼저 apidog test-case category --project <id>로 목록을 확인하세요. -r cli,json을 -r junit으로 바꾸면 같은 줄이 CI에서 실행됩니다. Claude Code를 에이전트로 사용한다면 Claude Code에서 Apidog CLI 사용하기부터 시작하세요. Apidog의 무료 플랜은 최대 4명의 사용자까지 지원합니다.

FAQ

Gemini API CLI는 무료인가요? CLI 자체는 Apache 2.0에 따라 무료이자 오픈소스입니다. 모든 호출은 일반적인 Gemini API 가격에 따라 당신의 API 키로 청구됩니다. 무료 티어가 무엇을 포함하는지는 Gemini API 무료 티어 가이드를 참고하세요.

gemini-api는 Gemini CLI와 같은 건가요? 아닙니다. Gemini CLI는 대화형 코딩 에이전트입니다. gemini-api는 다른 에이전트, 스크립트, CI 작업이 Gemini 모델과 관리형 에이전트에 접근하기 위해 호출하는 상태 비저장 도구입니다.

API 키 없이 명령을 테스트할 수 있나요? 예. --dry-run은 명령을 검증하고 네트워크 호출이나 키체인 읽기 없이 정확한 요청을 출력합니다. 이 글의 모든 예제는 0.4.5에서 이 방식으로 확인했습니다.

14MB보다 큰 파일은 어떻게 처리하나요? gemini-api files upload <file> --wait를 실행하고, 반환된 files/<id>를 보관한 뒤, analyze, transcribe, generate, image, video 또는 agent run의 -i에 전달하세요. 업로드는 48시간 후에 만료됩니다.

버전을 고정해야 하나요? 예, CI에서는 고정하세요. Google은 CLI가 베타인 동안 마이너 버전 간에 호환성을 깨는 변경이 발생할 수 있다고 밝혔습니다.