Tạo ảnh trong Gemini CLI: Hướng dẫn cấu hình MCP Server

Gemini CLI là terminal agent mã nguồn mở của Google, và MCP là giao thức được sử dụng để gọi các công cụ bên ngoài. Khi kết nối với một remote MCP server, cùng một phiên chat đang sửa mã nguồn cũng có thể tạo ảnh, video và giọng nói, lưu tập tin trực tiếp vào thư mục làm việc của bạn.

Tóm tắt nhanh: chạy lệnh gemini mcp add --transport http --scope user bananabanana https://bananabanana.pro/api/mcp -H "Authorization: Bearer $BB_KEY", xác nhận tin cậy thư mục khi CLI yêu cầu, sau đó kiểm tra gemini mcp list để thấy trạng thái xanh Connected. Ảnh có giá từ $0.03 mỗi lần tạo, trừ trực tiếp từ số dư tài khoản của bạn.

Cửa sổ terminal trên bàn làm việc với các khung tranh nhỏ xuất hiện từ bên trong, hình minh họa biên tập

Toàn bộ nội dung bên dưới đã được thử nghiệm thực tế với Gemini CLI 0.55.1 vào ngày 17 tháng 8 năm 2026 bằng một khóa bb_live_… đang hoạt động. Những điểm tài liệu chính thức khác biệt so với hành vi thực tế của CLI đều được nêu rõ.

Cài đặt nhanh

Chỉ cần hai lệnh. Lệnh đầu tiên đăng ký máy chủ:

export BB_KEY=bb_live_…   # create one at https://bananabanana.pro/profile
 
gemini mcp add --transport http --scope user \
  bananabanana https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer $BB_KEY"

Lệnh thứ hai kiểm tra kết nối:

gemini mcp list
# ✓ bananabanana: https://bananabanana.pro/api/mcp (http) - Connected

Nếu bạn thấy Disabled thay vì Connected, hãy đọc phần tiếp theo trước khi thay đổi bất kỳ cài đặt nào khác. Chi tiết nhỏ này đã khiến tôi mất khoảng năm phút xử lý.

Năm lưu ý tài liệu không đề cập

Cơ chế tin cậy thư mục âm thầm vô hiệu hóa mọi thứ. Chạy gemini mcp list trong thư mục mà CLI chưa tin cậy, bạn sẽ nhận được thông báo:

Warning: MCP servers are configured but disabled because this folder is untrusted.
User-level servers are also suppressed in untrusted folders to prevent accidental side-effects.

○ bananabanana: https://bananabanana.pro/api/mcp (http) - Disabled

Hãy chú ý dòng thứ hai: ngay cả máy chủ cấu hình với --scope user cũng bị vô hiệu hóa. CLI sẽ hỏi bạn xác nhận tin cậy ở lần chạy tương tác đầu tiên; nếu chạy bằng tập lệnh tự động, trạng thái tin cậy được lưu trong ~/.gemini/trustedFolders.json dưới dạng ánh xạ đường dẫn tới TRUST_FOLDER. Đây là biện pháp bảo mật hợp lý nhưng gây bối rối, bởi vì trạng thái "Disabled" không nêu rõ nguyên nhân là do thư mục.

gemini mcp add tạo khóa url, không phải httpUrl. Tài liệu mô tả tham số httpUrl cho giao thức Streamable HTTP. Tuy nhiên, cấu hình thực tế do CLI 0.55.1 tạo ra là:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $BB_KEY" }
    }
  }
}

Cả hai định dạng đều kết nối thành công. Nhưng nếu so sánh cấu hình trong tài liệu với tệp do CLI tạo ra, bạn có thể lầm tưởng một bên bị lỗi. Cả hai đều hoạt động.

Phạm vi mặc định là project, và khóa của bạn sẽ nằm ở đó. Nếu bỏ qua --scope user, khóa API sẽ được ghi vào .gemini/settings.json trong kho lưu trữ của bạn. Chỉ cần một lệnh git add . là khóa sẽ lọt vào lịch sử commit. Hãy luôn dùng --scope user hoặc giữ tiêu đề dưới dạng biến môi trường như mẫu trên.

Phép nội suy $BB_KEY hoạt động, nhưng lỗi trong im lặng. Khi biến được export, trạng thái là Connected. Nếu mở một cửa sổ terminal mới mà quên export biến, cùng cấu hình đó sẽ hiển thị Disconnected mà không đưa ra thông báo lỗi xác thực cụ thể. Bạn nên thêm dòng export vào file cấu hình shell của mình.

Gemini CLI thăm dò SSE và nhận phản hồi 405. Xem log máy chủ khi kết nối, trình tự diễn ra như sau: POST initialize (200), POST notification (202), GET /api/mcp (405), POST tools/list (200). Yêu cầu GET là nỗ lực của CLI nhằm mở kênh Server-Sent Events trên một máy chủ stateless. Phản hồi trả về 405, CLI bỏ qua và mọi thứ vẫn hoạt động trơn tru. Nếu tự vận hành máy chủ MCP riêng, bạn không cần bận tâm đến lỗi 405 này.

Bức tường gồm những cánh cửa khóa kín với một cánh cửa duy nhất hé mở và phát sáng, hình minh họa biên tập

Các công cụ được cung cấp và bảng giá

Trong phiên làm việc có chín công cụ, tương tự danh sách trên tài liệu công cụ. Bốn công cụ gọi miễn phí: list_models, get_account, get_result, list_generations. Các công cụ còn lại được tính phí theo từng lần tạo trừ vào số dư tài khoản.

Dịch vụ	Mô hình	Giá
Ảnh, 1K	Nano Banana 2 Lite	$0.03
Ảnh, 512 → 4K	Nano Banana 2	$0.03 – $0.13
Ảnh, 1K → 4K	Nano Banana Pro	$0.11 – $0.20
Video, 3–10 giây có âm thanh	Gemini Omni Flash	$0.10 mỗi giây
Video, 4–8 giây	Dòng Veo 3.1	lên đến $4.40 mỗi clip
Giọng nói	Gemini Flash TTS	$0.01 cho mỗi 200 ký tự

Các lệnh tạo video và tạo hàng loạt ảnh luôn báo giá trước. Agent nhận mức giá chính xác, số dư chưa bị trừ và quá trình chỉ bắt đầu khi đã xác nhận con số đó. Lỗi do bộ lọc an toàn hoặc sự cố upstream đều được hoàn tiền tự động vào tài khoản.

Nạp tiền có thêm phần thưởng: 5% từ $50, 10% từ $100, và mã khuyến mãi đang hoạt động cộng thêm 10% giá trị nạp. Nạp $100 kèm mã sẽ nhận được $120 trong tài khoản.

Tiền xu cạnh chồng tranh nhỏ có khung và dải phim xếp thành hình bậc thang, hình minh họa biên tập

Vì sao dùng Gemini gọi mô hình Nano Banana lại hợp lý?

Hai con đường dẫn đến cùng một cánh cổng phát sáng, một đường thẳng ngắn và một đường quanh co qua các trạm kiểm soát, hình minh họa biên tập

Việc Gemini CLI gọi một mô hình hình ảnh Gemini thông qua máy chủ trung gian thoạt nhìn có vẻ vòng vo. Bạn có thể chọn cách trực tiếp: tạo tài khoản thanh toán Google Cloud, kích hoạt API mô hình, thiết lập thông tin xác thực và quản lý hạn ngạch theo khu vực. Đó là lựa chọn phù hợp nếu công việc của bạn là xây dựng cơ sở hạ tầng.

Giải pháp của chúng tôi phục vụ nhu cầu khác: một token xác thực duy nhất, số dư trả trước, không cần tài khoản thanh toán đám mây, không phải gửi phiếu xin hạn ngạch, không ràng buộc vùng địa lý. Bạn cũng có thể truy cập các mô hình video Veo và Omni cùng tổng hợp giọng nói TTS qua cùng một kết nối, thanh toán theo từng lần tạo thay vì theo dự án. Nếu ưu tiên của bạn là sáng tạo nội dung thay vì vận hành nền tảng, đây là cách tiếp cận thuận tiện hơn rất nhiều.

Ở quy mô cực lớn, việc tự quản lý trên đám mây sẽ tiết kiệm chi phí hơn. Nhưng phương thức này giúp bạn bắt đầu chỉ trong hai phút và không lo bị phát sinh hóa đơn ngoài ý muốn.

Nếu bạn sử dụng các trình soạn thảo khác, cùng một máy chủ này có thể tích hợp với Claude Code, Cursor và Codex bằng cùng một khóa API.

Trường hợp ứng dụng thực tế: ảnh minh họa tài liệu

Một tình huống thực tế rất hiệu quả: kho mã nguồn chứa thư mục docs/ với mười hai trang, mỗi trang cần một ảnh tiêu đề theo phong cách đồng nhất.

Prompt trong phiên làm việc:

Read every heading in docs/*.md. For each file, generate a 16:9 illustration matching the page topic, in this style: editorial illustration, pastel paper background, dark ink details, violet and amber accents, no text. Use nano-banana-pro. Save each as docs/img/.png and add the image reference under the page title.

Agent đọc nội dung từng tệp tin, gọi generate_image cho mỗi trang, chờ qua get_result, tải ảnh về và chèn vào tệp markdown. Mười hai bức ảnh với giá $0.11 có tổng chi phí $1.32, toàn bộ diễn ra trong lúc bạn thưởng thức tách cà phê. Tất cả ảnh minh họa trong bài viết này đều được tạo ra từ chính quy trình đó bằng Nano Banana Pro với cùng một đoạn mô tả phong cách.

Hai lời khuyên trước khi thử: hãy tạo thử một ảnh mẫu để kiểm tra phong cách trước (sai mô tả trên 12 tệp sẽ lãng phí $1.32), và không nên bật cờ --trust để việc xác nhận thủ công từng công cụ trả phí giúp ngăn chặn vòng lặp ngoài ý muốn của agent.

Mười hai tấm thẻ minh họa nhỏ xếp thành lưới ngay ngắn trên bàn làm việc cùng chia sẻ một phong cách hình ảnh, hình minh họa biên tập

Có thể dùng OAuth thay cho khóa API không?

Gemini CLI hỗ trợ OAuth 2.0 cho các máy chủ MCP từ xa với cơ chế discovery và lệnh /mcp auth. Máy chủ của chúng tôi là một OAuth 2.1 authorization server đầy đủ (hỗ trợ dynamic client registration, PKCE S256, RFC 9728 discovery), giúp các ứng dụng như Claude Code và claude.ai đăng nhập trực tiếp mà không cần nhập khóa thủ công.

Quy trình sử dụng API key đã được kiểm thử toàn diện và hoạt động ổn định. Luồng OAuth trên Gemini CLI chưa được xác thực trong phiên này nên hãy xem đây là tính năng khả thi trên lý thuyết. Khởi tạo khóa API chỉ mất mười giây và không bao giờ hết hạn trừ khi bạn thu hồi.

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

Tệp cấu hình nằm ở đâu?

Tại ~/.gemini/settings.json cho phạm vi người dùng (user scope), hoặc .gemini/settings.json cho phạm vi dự án (project scope). Lệnh gemini mcp add --scope user sẽ ghi vào tệp đầu tiên.

Tại sao máy chủ hiển thị trạng thái Disabled?

Thư mục làm việc chưa được thêm vào danh sách tin cậy. Hãy xác nhận tin cậy khi khởi chạy tương tác hoặc thêm đường dẫn vào ~/.gemini/trustedFolders.json với giá trị TRUST_FOLDER. Máy chủ cấp người dùng cũng bị vô hiệu hóa trong các thư mục chưa tin cậy.

Tôi có thể giới hạn danh sách công cụ mà mô hình nhìn thấy không?

Có. Dùng cờ --include-tools và --exclude-tools trong lệnh gemini mcp add, hoặc các trường includeTools / excludeTools trong file cài đặt. Quy tắc loại trừ luôn có độ ưu tiên cao hơn.

Cấu hình có hoạt động trong dự án dùng chung của nhóm không?

Thiết lập máy chủ ở cấp độ dự án và gán khóa API qua biến môi trường, không ghi trực tiếp vào tệp. Mỗi lập trình viên chạy export BB_KEY=… với khóa riêng và tệp cấu hình trên git luôn sạch sẽ.

Điều gì xảy ra nếu việc tạo ảnh bị lỗi?

Bạn sẽ được hoàn tiền tự động vào tài khoản, bao gồm cả trường hợp bị từ chối bởi bộ lọc an toàn. Nếu câu lệnh ở mức ranh giới, bạn nên thử lại vì hệ thống kiểm tra an toàn đánh giá trên từng điểm ảnh hoàn thiện và lần chạy sau sẽ vẽ ra một bức tranh mới.

Nếu muốn thao tác trực quan, công cụ tạo ảnh trên web cho phép sử dụng cùng các mô hình với số dư chung. Trên terminal, hãy bắt đầu bằng lệnh list_models sau khi kết nối: lệnh này hoàn toàn miễn phí, hiển thị biểu giá hiện tại và kiểm tra kết nối trước khi bạn chi tiêu.