Sebastian Petrus

Posted on Oct 6 Originally published at apidog.com

Hướng dẫn sử dụng API Nano Banana 2.1

Google đã ra mắt Nano Banana 2.1 vào ngày 6 tháng 10 năm 2026. Mô hình có thể gọi qua Gemini API với ID gemini-nano-banana-2.1. Đây là bản cập nhật của Nano Banana 2 (Gemini 3.1 Flash Image), tập trung vào chất lượng ảnh, chỉnh sửa theo kiểu mask bằng prompt và tính nhất quán nhân vật tốt hơn qua nhiều lượt. Chi phí mỗi ảnh cũng bằng một nửa Nano Banana 2 ở các độ phân giải mà cả hai cùng hỗ trợ.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này đi từ terminal trống đến ảnh PNG đã lưu, sau đó mở rộng sang tỷ lệ khung hình, đầu ra 2K/4K, chỉnh sửa ảnh, chỉnh sửa đa lượt, ảnh tham chiếu, tạo nền bằng tìm kiếm và ước tính chi phí. Bạn có thể lưu mọi request trong Apidog để chạy lại và so sánh Nano Banana 2.1 với mô hình hiện tại.

Nếu cần bối cảnh trước khi bắt đầu, đọc bài Nano Banana 2.1 là gì.

Những gì bạn cần

Mục	Giá trị
URL cơ sở	`https://generativelanguage.googleapis.com/v1beta`
Header xác thực	`x-goog-api-key: $GEMINI_API_KEY`
ID mô hình	`gemini-nano-banana-2.1`
Điểm cuối	`POST /v1beta/interactions`
Độ phân giải	1K (mặc định), 2K, 4K
Đầu vào	Văn bản, hình ảnh (tối đa 14 tham chiếu), video
Python SDK	`pip install google-genai`
JavaScript SDK	`npm install @google/genai`

Các ví dụ bên dưới sử dụng Interactions API, là API được tài liệu tạo ảnh của Google sử dụng cho Nano Banana 2.1.

Bước 1: Lấy khóa API Gemini

Mở Google AI Studio và đăng nhập.
Vào Lấy khóa API, sau đó tạo khóa trong một dự án Google Cloud.
Bật thanh toán cho dự án. Theo trang giá của Google, tầng miễn phí của Nano Banana 2.1 là “Không có sẵn”, vì vậy API cần dự án trả phí.
Xuất khóa vào biến môi trường:

export GEMINI_API_KEY="khóa-của-bạn-tại-đây"

Google liên kết Nano Banana 2.1 với AI Studio playground để thử prompt nhanh. Tuy nhiên, Google chưa công bố số lượt tạo miễn phí có sẵn trong playground. Xem thêm cách sử dụng Nano Banana 2.1 miễn phí và hướng dẫn lấy khóa API Gemini.

Bước 2: Tạo hình ảnh đầu tiên

Gọi API bằng `curl`

Chạy request tối thiểu sau:

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": [
      {
        "type": "text",
        "text": "Tạo một bức tranh về một món chuối nano trong một nhà hàng sang trọng với chủ đề Gemini"
      }
    ]
  }'

Phản hồi là JSON. Dữ liệu ảnh được trả về dưới dạng base64 trong một khối nội dung hình ảnh, nên bạn cần SDK hoặc script để giải mã và ghi thành tệp.

Lưu ảnh bằng Python

Cài SDK:

pip install google-genai

Tạo ảnh và lưu thành generated_image.png:

from google import genai
import base64

client = genai.Client()  # Đọc biến GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Tạo một bức tranh về một món chuối nano trong một nhà hàng sang trọng với chủ đề Gemini",
)

with open("generated_image.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

interaction.output_image là khối ảnh được tạo cuối cùng. Trường data chứa base64, vì vậy phải giải mã trước khi ghi tệp.

Lưu ảnh bằng JavaScript

Cài SDK:

npm install @google/genai

Tạo file generate.mjs:

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input:
    "Tạo một bức tranh về một món chuối nano trong một nhà hàng sang trọng với chủ đề Gemini",
});

const image = interaction.output_image;

if (image) {
  fs.writeFileSync("nano-banana.png", Buffer.from(image.data, "base64"));
}

Các mô hình ảnh Gemini 3 có thể tạo tối đa hai “hình ảnh suy nghĩ” tạm thời để lập kế hoạch bố cục trước khi tạo ảnh cuối. Bạn không bị tính phí cho các hình ảnh này và không thể tắt quá trình “suy nghĩ” trong API.

Bước 3: Đặt tỷ lệ khung hình, độ phân giải và đầu ra chỉ có ảnh

Dùng response_format để kiểm soát phản hồi. Khi đặt "type": "image", API chỉ trả về ảnh thay vì văn bản hội thoại, giúp giảm payload và đơn giản hóa việc xử lý kết quả.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Một bức ảnh sản phẩm của máy xay cà phê màu đen mờ trên mặt bàn đá cẩm thạch",
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

Điểm cần kiểm tra trước khi chạy:

image_size chấp nhận 1K, 2K và 4K. Phải dùng chữ K viết hoa; 2k sẽ bị từ chối.
Nano Banana 2.1 không có mức 512px; mức này thuộc Nano Banana 2.
Tỷ lệ được hỗ trợ gồm: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8 và 8:1.
Ảnh 16:9 ở 2K có kích thước 2752x1536; ở 4K là 5504x3072.
Nếu cần cả văn bản lẫn ảnh, truyền danh sách định dạng phản hồi:

response_format=[
    {"type": "text"},
    {"type": "image"},
]

Bước 4: Chỉnh sửa ảnh hiện có

Để chỉnh sửa, gửi ảnh dưới dạng base64 trong một khối image, cùng với hướng dẫn văn bản cụ thể.

import base64

with open("living_room.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": (
                "Sử dụng hình ảnh phòng khách đã cung cấp, chỉ thay đổi ghế sofa màu xanh "
                "thành ghế sofa chesterfield da nâu kiểu cổ điển. Giữ nguyên phần còn lại "
                "của căn phòng, bao gồm cả gối trên sofa và ánh sáng."
            ),
        },
        {
            "type": "image",
            "data": image_b64,
            "mime_type": "image/png",
        },
    ],
)

Chỉnh sửa kiểu mask mà không cần tệp mask

Nano Banana 2.1 không yêu cầu tải một tệp mask riêng. Thay vào đó, mô tả vùng cần thay đổi bằng prompt.

Sử dụng hình ảnh đã cung cấp, chỉ thay đổi [thành phần cụ thể] thành [thành phần/mô tả mới]. Giữ nguyên mọi thứ khác trong hình ảnh, bảo toàn phong cách, ánh sáng và bố cục gốc.

Để giảm nguy cơ mô hình vẽ lại toàn bộ ảnh:

Chỉ rõ một thành phần cần sửa.
Mô tả thành phần thay thế càng cụ thể càng tốt.
Liệt kê các thành phần phải được giữ nguyên.

Ví dụ, thay vì viết “làm ghế sofa đẹp hơn”, hãy nêu rõ màu, chất liệu, kiểu dáng và những chi tiết không được thay đổi.

Bước 5: Chỉnh sửa đa lượt

Google khuyến nghị dùng chỉnh sửa đa lượt để tinh chỉnh dần một ảnh. Gửi id của tương tác trước đó qua previous_interaction_id, rồi chỉ mô tả thay đổi mới.

interaction_2 = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=(
        "Cập nhật infographic này sang tiếng Tây Ban Nha. "
        "Không thay đổi bất kỳ yếu tố nào khác của hình ảnh."
    ),
    previous_interaction_id=interaction.id,
    response_format={
        "type": "image",
        "mime_type": "image/png",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

Khi gọi REST API, thêm trường này vào JSON body:

{
  "previous_interaction_id": "ID_CUA_TUONG_TAC_TRUOC"
}

Đây là điểm quan trọng khi bạn cần giữ nhận diện nhân vật hoặc sản phẩm qua nhiều vòng chỉnh sửa.

Bước 6: Kết hợp tối đa 14 ảnh tham chiếu

Thêm nhiều khối image vào mảng input. Theo tài liệu của Google, Nano Banana 2.1 hỗ trợ tối đa:

10 ảnh đối tượng có độ trung thực cao
4 ảnh nhân vật
Tổng cộng 14 ảnh tham chiếu

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {
            "type": "text",
            "text": "Một bức ảnh nhóm văn phòng của những người này, họ đang làm mặt hài hước.",
        },
        {"type": "image", "data": person_1_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_2_b64, "mime_type": "image/png"},
        {"type": "image", "data": person_3_b64, "mime_type": "image/png"},
    ],
    response_format={
        "type": "image",
        "aspect_ratio": "5:4",
        "image_size": "2K",
    },
)

Ảnh tham chiếu được tính là token đầu vào. Chi phí đầu vào của 2.1 cao gấp ba Nano Banana 2, vì vậy các workflow sử dụng nhiều ảnh tham chiếu sẽ thu hẹp chênh lệch chi phí. Hãy đo token và chi phí thực tế trước khi chuyển toàn bộ workload.

Bước 7: Tạo ảnh có nền ngữ cảnh bằng Google Search

Với ảnh phụ thuộc dữ liệu hoặc sự kiện hiện tại, thêm công cụ tìm kiếm vào request.

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="Một bức tranh chi tiết về một con bướm Timareta đậu trên một bông hoa",
    tools=[
        {
            "type": "google_search",
            "search_types": ["web_search", "image_search"],
        }
    ],
)

Lưu ý:

Chỉ dùng {"type": "google_search"} để bật tìm kiếm web.
Thêm image_search để mô hình dùng ảnh web làm ngữ cảnh trực quan.
Tìm kiếm hình ảnh là khả năng chỉ Nano Banana 2.1 và Nano Banana 2 hỗ trợ trong trường hợp này.
Tạo nền không thể sử dụng ảnh người thật từ tìm kiếm.
Nếu hiển thị kết quả có tạo nền cho người dùng, Google yêu cầu hiển thị search_suggestions trả về trong bước google_search_result.

Bước 8: Kiểm tra request trong Apidog

Script phù hợp cho việc tạo ảnh hàng loạt. Nhưng khi cần xác minh prompt, API key và model vẫn hoạt động, một request đã lưu trong Apidog sẽ tiện hơn.

Tạo Environment và thêm biến GEMINI_API_KEY.
Tạo request:

POST https://generativelanguage.googleapis.com/v1beta/interactions

Thêm header:

x-goog-api-key: {{GEMINI_API_KEY}}

Dán JSON body chứa model, input và response_format.
Nhấn Gửi.
Thêm script hậu phản hồi để kiểm tra status và khối ảnh:

pm.test("status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("response contains an image block", () => {
  const steps = pm.response.json().steps || [];

  const hasImage = steps.some(
    (step) =>
      step.type === "model_output" &&
      (step.content || []).some(
        (content) => content.type === "image" && content.data
      )
  );

  pm.expect(hasImage).to.be.true;
});

Nhân đôi request, đổi model thành gemini-3.1-flash-image, rồi gửi cả hai request với cùng một prompt.

Bạn sẽ có kiểm tra song song giữa Nano Banana 2.1 và Nano Banana 2, bao gồm trạng thái, thời gian phản hồi và kích thước response. Để so sánh rộng hơn, xem Nano Banana 2.1 vs Nano Banana 2 vs Pro.

Chi phí

Giá theo tầng trả phí, theo trang giá Google vào ngày 7 tháng 10 năm 2026:

Mô hình	Đầu vào / 1M	Hình ảnh 1K	Hình ảnh 2K	Hình ảnh 4K	Lô 1K
Nano Banana 2.1	$1.50	$0.0336	$0.0504	$0.0756	$0.0168
Nano Banana 2	$0.50	$0.067	$0.101	$0.151	$0.034
Nano Banana Pro	$2.00	$0.134	$0.134	$0.24	$0.067

Đầu ra hình ảnh của 2.1 có giá $30 cho mỗi 1 triệu token:

Ảnh 1K: 1.120 token
Ảnh 2K: 1.680 token
Ảnh 4K: 2.520 token

Đầu ra văn bản và token suy nghĩ có giá $7.50 cho mỗi 1 triệu token. Tìm kiếm tạo nền bao gồm 5.000 request miễn phí mỗi tháng, dùng chung cho các mô hình Gemini 3.x; sau đó là $14 cho mỗi 1.000 request.

Ví dụ chi phí: 1.000 ảnh sản phẩm 2K

Giả sử mỗi prompt văn bản có khoảng 100 token đầu vào:

Đầu ra: 1.000 × $0.0504 = $50.40
Đầu vào: 100.000 × $1.50 / 1M = $0.15
Tổng: khoảng $50.55, chưa gồm token văn bản suy nghĩ

Cùng workload này trên Nano Banana 2 có giá khoảng $101.

Nếu dùng Batch API, giá 2K của 2.1 giảm còn $0.0252 mỗi ảnh. Chi phí đầu ra cho 1.000 ảnh giảm còn $25.20, đổi lại thời gian hoàn thành có thể lên đến 24 giờ. Xem thêm phân tích giá API Nano Banana 2.

Lỗi thường gặp

Các lỗi sau là hành vi API Gemini phổ biến, không phải lỗi riêng của Nano Banana 2.1.

Lỗi	Nguyên nhân có thể	Cách khắc phục
`400 INVALID_ARGUMENT`	`image_size` viết thường, tỷ lệ không hỗ trợ, `input` sai cấu trúc	Dùng `2K` thay vì `2k`; kiểm tra danh sách tỷ lệ và JSON body
`403 PERMISSION_DENIED`	API key sai hoặc dự án chưa bật thanh toán	Kiểm tra key và bật billing
`404 NOT_FOUND`	Sai ID mô hình	Dùng chính xác `gemini-nano-banana-2.1`
`429 RESOURCE_EXHAUSTED`	Đạt giới hạn tỷ lệ	Retry sau hoặc dùng Batch
`500` / `503`	Lỗi máy chủ tạm thời	Retry với exponential backoff
`200` nhưng không có ảnh	Prompt bị chặn hoặc phản hồi chỉ có văn bản	Đặt `"type": "image"` và diễn đạt lại prompt

Ví dụ retry với exponential backoff trong Python:

import time

for attempt in range(5):
    try:
        interaction = client.interactions.create(
            model="gemini-nano-banana-2.1",
            input="Một bức ảnh sản phẩm tối giản của bình nước bằng thép không gỉ",
        )
        break
    except Exception:
        if attempt == 4:
            raise
        time.sleep(2**attempt)

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

Có tầng miễn phí cho API Nano Banana 2.1 không?

Không. Google liệt kê tầng miễn phí của API là “Không có sẵn”. AI Studio playground liên kết với 2.1, nhưng Google chưa công bố giới hạn miễn phí tại đó.

Nano Banana 2.1 có phải là thay thế trực tiếp cho Nano Banana 2 không?

Phần lớn là có. Đổi ID mô hình sang gemini-nano-banana-2.1. Tuy nhiên, bạn mất mức 512px và token đầu vào đắt hơn, nên hãy kiểm tra chi phí với workflow sử dụng nhiều ảnh tham chiếu.

Ảnh tạo ra có watermark không?

Có. Tất cả đầu ra đều có watermark SynthID.

Có thể tạo ảnh từ video không?

Có. Nano Banana 2.1 chấp nhận khối đầu vào video, chẳng hạn URL YouTube, cùng prompt văn bản.

Hướng dẫn API Nano Banana 2 cũ còn áp dụng không?

Các khái niệm vẫn áp dụng. Xem hướng dẫn API Nano Banana 2 cho mô hình trước đó.

Tóm tắt

Nano Banana 2.1 giữ cấu trúc Interactions API nhưng cung cấp chất lượng ảnh tốt hơn và chi phí mỗi ảnh bằng một nửa Nano Banana 2 ở các độ phân giải tương ứng.

Quy trình triển khai thực tế:

Tạo API key trong dự án đã bật thanh toán.
Chạy request tạo ảnh tối thiểu.
Lưu và giải mã base64 thành PNG.
Dùng response_format để khóa tỷ lệ và độ phân giải.
Dùng previous_interaction_id cho chỉnh sửa đa lượt.
Lưu request trong Apidog, thêm assertion cho status và image block.
Nhân đôi request với gemini-3.1-flash-image để đo trực tiếp chất lượng, tốc độ và chi phí trên prompt của bạn.

DEV Community

Hướng dẫn sử dụng API Nano Banana 2.1

Những gì bạn cần

Bước 1: Lấy khóa API Gemini

Bước 2: Tạo hình ảnh đầu tiên

Gọi API bằng `curl`

Lưu ảnh bằng Python

Lưu ảnh bằng JavaScript

Bước 3: Đặt tỷ lệ khung hình, độ phân giải và đầu ra chỉ có ảnh

Bước 4: Chỉnh sửa ảnh hiện có

Chỉnh sửa kiểu mask mà không cần tệp mask

Bước 5: Chỉnh sửa đa lượt

Bước 6: Kết hợp tối đa 14 ảnh tham chiếu

Bước 7: Tạo ảnh có nền ngữ cảnh bằng Google Search

Bước 8: Kiểm tra request trong Apidog

Chi phí

Ví dụ chi phí: 1.000 ảnh sản phẩm 2K

Lỗi thường gặp

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

Tóm tắt

Top comments (0)

Những gì bạn cần

Bước 1: Lấy khóa API Gemini

Bước 2: Tạo hình ảnh đầu tiên

Gọi API bằng curl

Lưu ảnh bằng Python

Lưu ảnh bằng JavaScript

Bước 3: Đặt tỷ lệ khung hình, độ phân giải và đầu ra chỉ có ảnh

Bước 4: Chỉnh sửa ảnh hiện có

Chỉnh sửa kiểu mask mà không cần tệp mask

Bước 5: Chỉnh sửa đa lượt

Bước 6: Kết hợp tối đa 14 ảnh tham chiếu

Bước 7: Tạo ảnh có nền ngữ cảnh bằng Google Search

Bước 8: Kiểm tra request trong Apidog

Chi phí

Ví dụ chi phí: 1.000 ảnh sản phẩm 2K

Lỗi thường gặp

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

Tóm tắt

Gọi API bằng `curl`