Gemini API CLI

Gemini API CLI (gemini-api) là một ứng dụng dòng lệnh không trạng thái, không phụ thuộc, được xây dựng cho các tác nhân AI có quyền truy cập shell (và có thể sử dụng từ tập lệnh và CI). Sau đó, tác nhân lập trình có thể tạo văn bản do AI tạo và nội dung nghe nhìn, phân tích tệp và uỷ quyền nhiệm vụ cho các tác nhân do Gemini quản lý. Công cụ này hoạt động với Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes hoặc bất kỳ môi trường shell nào.

Mỗi tính năng đều chạy dưới dạng một lệnh shell tiêu chuẩn trên Interactions API. Chạy các lệnh tương tự từ một quy trình con của tác nhân, thiết bị đầu cuối hoặc quy trình 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

Chọn công cụ Gemini phù hợp

Sử dụng gemini-api khi một tác nhân hoặc tập lệnh cần gọi Gemini trực tiếp từ shell mà không cần thêm mã SDK vào dự án của bạn. Sử dụng SDK và thiết lập tác nhân lập trình khi bạn tích hợp Gemini vào một ứng dụng:

Cách hoạt động

Các lệnh gọi REST thô và CLI tương tác thường gây ra vấn đề cho tác nhân lập trình. Nội dung nghe nhìn Base64 lấp đầy cửa sổ ngữ cảnh, lời nhắc tương tác chặn các quy trình con và dữ liệu huấn luyện cũ gây ra các cờ ảo giác.

Bốn lựa chọn thiết kế giúp gemini-api trở thành một công cụ đáng tin cậy cho nhân viên hỗ trợ:

• Tra cứu giản đồ khi không có mạng: Truyền --usage để in cây lệnh (trong KDL) hoặc --schema để in Giản đồ JSON cho các yêu cầu --body.
• Tệp trên ổ đĩa, đường dẫn trên stdout: Các lệnh về nội dung nghe nhìn và bản chép lời sẽ ghi tệp vào ổ đĩa và chỉ in đường dẫn đầu ra, giữ dữ liệu nhị phân nằm ngoài ngữ cảnh.
• Chạy thử và kết quả có cấu trúc: --dry-run xác thực dữ liệu đầu vào, loại bỏ thông tin xác thực và xem trước yêu cầu HTTP khi không có mạng. Truyền -o json, -o toon hoặc --jq để có kết quả có thể đọc được bằng máy. Thêm --agent-mode để trả về lỗi JSON có cấu trúc trên stderr và kiểm tra mã thoát để xử lý lỗi. Các lệnh không bao giờ nhắc trừ phi bạn truyền --interactive.
• Không có trạng thái theo mặc định: Các lệnh không giữ trạng thái cục bộ ẩn. Liên kết rõ ràng công việc nhiều bước với --previous-interaction-id, URI files/<id> đã tải lên hoặc mã nhận dạng tương tác trong nền.

Với -o json, các lệnh nội dung nghe nhìn vẫn ghi tệp vào ổ đĩa và in siêu dữ liệu vào stdout:

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

Bắt đầu

Cài đặt CLI, đặt gemini-api vào PATH, đặt GEMINI_API_KEY và thêm quy tắc sử dụng vào tác nhân lập trình.

1. Cài đặt tệp nhị phân

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. Thiết lập phương thức xác thực và xác minh

Tạo khoá API trong Google AI Studio (xem phần Khoá API). Đặt GEMINI_API_KEY trong shell và môi trường quy trình con của tác nhân:

export GEMINI_API_KEY="YOUR_API_KEY"

Trên máy trạm cục bộ, bạn có thể lưu khoá trong chuỗi khoá của hệ điều hành (Chuỗi khoá macOS, Dịch vụ bí mật Linux hoặc Trình quản lý thông tin xác thực Windows). Hãy truyền --no-keyring để lưu trữ khoá trong ~/.config/gemini-api/config.yaml:

# 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. Đưa ra chỉ dẫn cho nhân viên hỗ trợ

Thêm đoạn mã này vào AGENTS.md, CLAUDE.md, .cursorrules hoặc câu lệnh hệ thống của dự án để tác nhân lập trình biết cách sử dụng 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`.

Sau đó, hãy ra lệnh cho tác nhân lập trình như bình thường:

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.

Lệnh

Chạy gemini-api --help để liệt kê tất cả các lệnh hoặc gemini-api explore để duyệt xem các lệnh đó theo cách tương tác.

Quy trình công việc

Mỗi lệnh đều mặc định sử dụng một mô hình phù hợp với nhiệm vụ của lệnh đó. Truyền --model (-m) để chọn một mô hình khác. Chạy gemini-api models để liệt kê các tuỳ chọn có sẵn.

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

Các tác nhân xây dựng giao diện người dùng web hoặc di động có thể tạo phần giữ chỗ, biểu tượng và hình ảnh chính bằng Nano Banana. Truyền đường dẫn đã tạo trở lại bằng -i để chỉnh sửa hình ảnh:

# 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

Truyền -i nhiều lần để kết hợp các hình ảnh tham khảo, chẳng hạn như một nhân vật và một hướng dẫn về phong cách.

Tổng hợp giọng nói

gemini-api tts tổng hợp âm thanh WAV 24 kHz cho các tín hiệu giao diện người dùng, bản xem trước hỗ trợ tiếp cận và hướng dẫn bằng giọng nói. Giọng nói mặc định là Kore; hãy chọn một giọng nói khác bằng --voice. Đối với cuộc hội thoại có hai người nói, hãy gắn nhãn cho từng lượt nói trong câu lệnh và liên kết người nói với giọng nói:

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

Nhạc và video

Sáng tác bản nhạc gốc bằng Lyria và tạo đoạn video MP4 bằng 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

Theo mặc định, lệnh video sẽ đợi quá trình tạo hoàn tất và ghi tệp MP4 vào ổ đĩa. Truyền --async để trả về mã nhận dạng tương tác ngay lập tức, sau đó chạy gemini-api video --resume <id> --out <path> sau. Truyền -i để tạo ảnh động cho một hình ảnh hiện có.

Tạo văn bản

gemini-api generate truyền trực tuyến văn bản đến stdout:

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

Thêm --stdin để đưa văn bản vào câu lệnh. Truyền --previous-interaction-id để tiếp tục một lượt tương tác trước đó.

Phân tích và chép lời tài liệu

analyze trả lời các câu hỏi về tệp PDF, bảng tính, ảnh chụp màn hình, tệp âm thanh và video cũng như URL công khai trên YouTube. transcribe ghi bản chép lời được định dạng (md, text, json hoặc srt) vào ổ đĩa:

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

Truyền -i nhiều lần đến analyze để so sánh các tệp, chẳng hạn như ảnh chụp màn hình trước và sau.

gemini-api gửi tệp cục bộ dưới dạng nội tuyến có kích thước tối đa 14 MB (20 MB sau khi mã hoá base64). Đối với các tệp lớn hơn, hãy tải lên một lần bằng files upload --wait và sử dụng lại URI files/<id> được trả về:

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

Chạy và quản lý tác nhân

Tác nhân lập trình có thể uỷ quyền các nhiệm vụ nghiên cứu hoặc nhiệm vụ trong hộp cát gồm nhiều bước cho các tác nhân do Gemini quản lý, chẳng hạn như tác nhân Deep Research. Truyền --background --stream=false để nhận mã nhận dạng lượt tương tác ngay lập tức thay vì giữ cho luồng luôn mở:

# 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

Chạy gemini-api agent cancel <id> để dừng một công việc đang chạy. Bạn cũng có thể chạy tác nhân Antigravity trong một hộp cát từ xa bằng agent run hoặc quản lý tác nhân tuỳ chỉnh bằng agent create, list, get và delete. Xem phần Môi trường để định cấu hình hộp cát của tác nhân.

Nội dung yêu cầu tuỳ chỉnh

Đối với các tuỳ chọn không có cờ chuyên dụng, hãy truyền tải trọng JSON thô của Interactions API bằng --body (nội tuyến hoặc dưới dạng @file.json). Truyền --body để đặt giản đồ response_format, công cụ gọi hàm, generation_config hoặc "store": false. Trước tiên, hãy chạy gemini-api <command> --schema để kiểm tra các trường hợp lệ:

# 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 hợp nhất với cờ lệnh. Nếu cả hai đều đặt cùng một khoá, thì lệnh sẽ không thành công với mã thoát 2, vì vậy, các dữ liệu đầu vào xung đột sẽ nhanh chóng không thành công.

Mã thoát

Mỗi lệnh trả về một mã thoát đã nhập để tập lệnh và tác nhân có thể xử lý lỗi mà không cần phân tích cú pháp văn bản lỗi. Ví dụ: 3 báo hiệu vấn đề về xác thực và 2 báo hiệu cú pháp lệnh không hợp lệ:

Chạy gemini-api --help-global để liệt kê các cờ chung được mọi lệnh chia sẻ (xác thực, đầu ra, mạng và chẩn đoán).

Các điểm hạn chế

• Các lệnh truyền trực tuyến (generate và agent run) yêu cầu --stream=false khi kết hợp với -o json hoặc --jq để trả về một đối tượng phản hồi JSON duy nhất.
• Dữ liệu đầu vào của tệp -i cùng dòng có giới hạn là 14 MB dữ liệu tệp thô (tải trọng yêu cầu là 20 MB, bao gồm cả mã hoá base64). Tải tệp lớn lên bằng gemini-api files upload. Files API sẽ xoá các tệp đã tải lên sau 48 giờ.
• gemini-api hỗ trợ các yêu cầu HTTP tiêu chuẩn, truyền trực tuyến SSE và thăm dò không đồng bộ, chứ không hỗ trợ WebSocket hai chiều. Để truyền trực tuyến video và giọng nói theo thời gian thực, hãy sử dụng Live API với SDK GenAI của Google.

Bước tiếp theo

• Thiết lập tác nhân lập trình
• Interactions API
• Tác nhân được quản lý của Gemini
• gemini-api-cli trên GitHub