Gemini API CLI: Cho Coding Agent của bạn gọi Gemini xử lý ảnh, video, PDF và Deep Research

Gemini API CLI (gemini-api) là client dòng lệnh mã nguồn mở của Google dành cho Gemini API, được xây dựng cho các coding agent như Claude Code, Codex, Cursor và Antigravity. Chỉ cần cài một binary Go duy nhất, đặt GEMINI_API_KEY, và agent của bạn có thể tạo ảnh, video, giọng nói và nhạc, phân tích PDF và bản ghi âm, chuyển audio thành SRT, và khởi chạy Deep Research ở chế độ nền.

Dưới đây: cài đặt, xác thực, các lệnh mà agent của bạn sẽ chạy, điểm khác biệt so với Gemini CLI, và cách kết hợp nó với Apidog CLI. Mọi flag đều được sao chép từ gemini-api --help trên phiên bản 0.4.5, phát hành ngày 30 tháng 10 năm 2026.

Gemini API CLI là gì?

Gemini API CLI là một client không trạng thái, chỉ một binary duy nhất cho Interactions API của Google. Mỗi lệnh là một lệnh gọi HTTP: bạn đưa vào một prompt, và nhận ra một đường dẫn tệp, bản chép lời, kết quả phân tích hoặc ID tương tác. Đây là công cụ mà agent hiện có của bạn gọi đến khi một tác vụ cần Gemini.

Trang tài liệu chính thức của Google gọi nó là “một bản phát hành beta mã nguồn mở, phát triển song hành cùng Interactions API”. Mã nguồn nằm tại google-gemini/gemini-api-cli theo giấy phép Apache 2.0, và chạy trên macOS, Linux và Windows.

Dưới đây là những gì gemini-api --help liệt kê trên 0.4.5, kèm model mặc định của từng lệnh:

Gemini API CLI so với Gemini CLI

Hai cái tên khá giống nhau, nên đây là điểm phân biệt. Gemini CLI (@google/gemini-cli) là một coding agent tương tác, một lựa chọn thay thế Claude Code mà bạn trò chuyện cùng. Gemini API CLI (gemini-api) hoàn toàn không có vòng lặp agent. Nó là công cụ để một agent khác chạy.

Nếu bạn làm việc trong Claude Code hoặc Codex và muốn có các model media và nghiên cứu của Gemini ngay trong luồng làm việc đó, hãy dùng gemini-api. Đây cũng chính là mô hình của OpenAI CLI, nhưng hướng tới Google.

Cách cài đặt Gemini API CLI

Chọn một trong bốn cách từ README.

macOS và 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

Binary dựng sẵn: tải tệp nén cho nền tảng của bạn từ GitHub Releases, đối chiếu với checksums.txt, rồi đặt gemini-api vào PATH. Chúng tôi đã dùng tệp Darwin_arm64; lệnh shasum -a 256 -c checksums.txt --ignore-missing in ra OK.

Google cảnh báo rằng các thay đổi gây hỏng có thể xuất hiện giữa các phiên bản minor, nên hãy ghim một bản phát hành trong CI. Tài liệu hiển thị script cài đặt với GEMINI_VERSION=<release-tag> đặt trước bash.

Xác nhận cài đặt:

gemini-api version
# gemini-api 0.4.5

Xác thực Gemini API CLI

Tạo một key trong Google AI Studio (hướng dẫn của chúng tôi về cách lấy Gemini API key miễn phí sẽ dẫn bạn qua từng bước), rồi export nó:

export GEMINI_API_KEY="YOUR_API_KEY"

Trên máy trạm của riêng bạn, thay vào đó bạn có thể lưu trữ nó:

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

configure lưu key vào keychain của hệ điều hành (macOS Keychain, Linux Secret Service hoặc Windows Credential Manager). Thêm flag toàn cục --no-keyring để thay vào đó giữ nó trong ~/.config/gemini-api/config.yaml. whoami cho biết thông tin xác thực nào đang hoạt động và đến từ đâu.

Khi chưa đặt key, gemini-api --help in ra một dòng hướng tới chính agent: một API key “phải do người dùng tạo thủ công trong Google AI Studio. Hãy dừng lại và yêu cầu người dùng tạo một key”. Agent của bạn sẽ hỏi bạn thay vì tự cấu hình key.

Xem trước mọi lệnh gọi với --dry-run

--dry-run kiểm tra tính hợp lệ của các flag và in ra request với thông tin xác thực đã được che, không gọi mạng và không đọc keychain. Nó hoạt động ngay cả trước khi bạn đặt key, và đó là cách chúng tôi kiểm tra mọi ví dụ ở đây.

Đây là một dry run thực tế của một tác vụ Deep Research chạy nền:

Mọi lệnh đều POST tới https://generativelanguage.googleapis.com/v1beta/interactions. Thêm -o json để nhận một đối tượng JSON cho mỗi request trên stdout, giúp agent có thể phân tích trước khi tiêu tốn một token.

Các lệnh Gemini API CLI mà agent của bạn sẽ chạy

Tạo và chỉnh sửa ảnh

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

Các lệnh media ghi tệp ra và chỉ in đường dẫn của nó, nên agent sẽ bắt lấy đường dẫn đó bằng $(...) và tiếp tục công việc. image cũng nhận --aspect-ratio và --image-size (512, 1K, 2K hoặc 4K). Model mặc định là Nano Banana 2.1; xem hướng dẫn Nano Banana 2.1 API của chúng tôi để biết nó làm tốt những gì.

Tạo video, giọng nói và nhạc

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 mất nhiều thời gian hơn, nên video sẽ tự động polling giúp bạn. Dùng --async để nhận handle của operation ngay lập tức và --resume <id> để tiếp tục polling sau đó. --resolution mặc định là 720p.

Phân tích PDF, ảnh và URL YouTube

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 có thể lặp lại nhiều lần và chấp nhận đường dẫn cục bộ, URI files/<id>, hoặc URL YouTube. Input nội tuyến (inline) bị giới hạn ở khoảng 14 MB thô. Với tệp lớn hơn, hãy tải lên một lần và tái sử dụng 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"

Các tệp đã tải lên sẽ bị xóa sau 48 giờ.

Chuyển audio và video thành văn bản

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

--format nhận md (mặc định), text, json hoặc srt. Thêm --no-speakers hoặc --no-timestamps để loại bỏ một trong hai khỏi đầu ra.

Chạy Deep Research ở chế độ nền

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 trả về một ID tương tác ngay lập tức thay vì giữ một luồng stream mở. Agent lưu ID đó, làm việc khác, rồi kiểm tra lại bằng agent status. agent cancel dừng một lần chạy. Phần trợ giúp của 0.4.5 cũng liệt kê deep-research-max-preview-04-2026 và antigravity-preview-05-2026 là các agent được quản lý.

Những flag giúp gemini-api an toàn cho agent

Đây là những flag toàn cục đáng đưa vào hướng dẫn cho agent của bạn, tất cả đều từ gemini-api --help-global:

• --agent-mode (hoặc GEMINI_CLI_AGENT_MODE=1): lỗi JSON có cấu trúc trên stderr và đầu ra TOON gọn gàng trên stdout.
• -o, --output-format: pretty, json, yaml, table hoặc toon.
• -q, --jq: lọc đầu ra ngay tại chỗ, ví dụ --jq '.id'.
• --no-interactive: không có prompt hay form TUI, điều mà một agent headless cần.
• --usage: toàn bộ cây lệnh dưới dạng KDL mà máy có thể đọc được.
• --schema (theo từng lệnh): JSON Schema cho payload --body.

Mã thoát (exit code) cho agent biết đã xảy ra lỗi gì mà không cần phân tích văn bản: 0 thành công, 1 lỗi runtime hoặc API, 2 lỗi cách dùng hoặc xác thực dữ liệu, 3 lỗi xác thực danh tính. Một điểm cần lưu ý: các lệnh streaming (generate, agent run) cần --stream=false thì -o json hoặc --jq mới cho ra một kết quả duy nhất có thể phân tích được.

Cung cấp Gemini API CLI cho coding agent của bạn

README của Google có sẵn một đoạn để dán vào AGENTS.md, CLAUDE.md hoặc .cursorrules. Đã lược gọn:

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.

Hãy đảm bảo GEMINI_API_KEY tiếp cận được môi trường tiến trình con của agent. Sau đó ra lệnh như bình thường: “Build the landing page, use Gemini for a mascot image and a 20-second voiceover, and start a Deep Research run on competing products.” Agent sẽ tự chọn các lệnh.

Những gì nó không làm được: giọng nói hoặc video thời gian thực. Không có hỗ trợ WebSocket, nên Live API vẫn cần tới các GenAI SDK.

Kiểm thử API bạn xây dựng với Apidog CLI

gemini-api cung cấp cho agent của bạn các model của Gemini. Nó không biết gì về API của chính bạn: endpoint /summarize hay /thumbnail mà ứng dụng của bạn bọc quanh Gemini, các môi trường của nó, hay những assertion chứng minh một bản phát hành không bị hỏng. Đó là việc của Apidog CLI, và cùng một agent có thể chạy cả hai.

Thiết lập một lần:

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

Sau đó đưa cho agent một prompt duy nhất:

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.

Agent kiểm tra câu trả lời của Gemini bằng gemini-api, sau đó đọc schema của Apidog trước khi viết payload, xác thực nó, rồi tạo và chạy test case:

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 chỉ ra một cái bẫy: test case cần một categoryId hợp lệ, nên hãy liệt kê chúng trước bằng apidog test-case category --project <id>. Đổi -r cli,json thành -r junit và dòng lệnh tương tự sẽ chạy được trong CI. Nếu Claude Code là agent của bạn, hãy bắt đầu với Apidog CLI trong Claude Code. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.

Câu hỏi thường gặp

Gemini API CLI có miễn phí không? Bản thân CLI là miễn phí và mã nguồn mở theo giấy phép Apache 2.0. Mọi lệnh gọi đều tính phí vào API key của bạn theo bảng giá Gemini API thông thường. Để biết gói miễn phí bao gồm những gì, xem hướng dẫn về gói miễn phí của Gemini API của chúng tôi.

gemini-api có giống Gemini CLI không? Không. Gemini CLI là một coding agent tương tác. gemini-api là một công cụ không trạng thái mà các agent, script và tác vụ CI khác gọi đến để kết nối tới các model và agent được quản lý của Gemini.

Tôi có thể kiểm thử các lệnh mà không cần API key không? Có. --dry-run xác thực lệnh và in ra request chính xác mà không gọi mạng và không đọc keychain. Mọi ví dụ trong bài viết này đều được kiểm tra theo cách đó trên 0.4.5.

Tôi xử lý các tệp lớn hơn 14 MB như thế nào? Chạy gemini-api files upload <file> --wait, giữ lại files/<id> được trả về, và truyền nó vào -i trong analyze, transcribe, generate, image, video hoặc agent run. Các tệp tải lên sẽ hết hạn sau 48 giờ.

Tôi có nên ghim phiên bản không? Có, trong CI. Google cho biết các thay đổi gây hỏng có thể xảy ra giữa các phiên bản minor trong thời gian CLI còn ở bản beta.