Claude Opus 5.5 đã có trên SeedRouter

Cách sử dụng Nano Banana 2 API: khóa, yêu cầu và kết quả

Hướng dẫn dùng Nano Banana 2 API từng bước: tạo khóa, gửi yêu cầu generateContent, truy vấn tác vụ, thêm ảnh tham chiếu và để một coding agent tự chạy.

Đọc dạng Markdown

Để dùng Nano Banana 2 API, hãy tạo một khóa API, gửi thân yêu cầu generateContent của Google kèm trường model tới một endpoint, rồi truy vấn tác vụ được trả về cho tới khi URL ảnh sẵn sàng. Các bước tương tự áp dụng cho Nano Banana Pro và Nano Banana 2 Lite; chỉ giá trị model thay đổi.

Hướng dẫn này đi qua từng bước với code chạy được, rồi chỉ cách chỉnh sửa bằng ảnh tham chiếu và cách giao việc cho một coding agent.

Cần chuẩn bị gì trước yêu cầu đầu tiên?

  1. Một khóa API. Tạo khóa trên trang khóa API và giữ nó trên máy chủ của bạn. Đừng bao giờ đặt nó trong code chạy trên trình duyệt.
  2. Tín dụng. Nạp số dư trên trang thanh toán. Tín dụng không bao giờ hết hạn, và yêu cầu thất bại không bị tính phí.
  3. Một ID mô hình. gemini-3.1-flash-image tính giá cố định mỗi ảnh; gemini-3.1-flash-image-official tính theo token. Xem hướng dẫn giá để chọn.
export SEEDROUTER_API_KEY="your-key"

Gửi yêu cầu Nano Banana 2 thế nào?

Gửi POST tới /v1/images/generations. Thân yêu cầu có dạng generateContent của Google cộng thêm model:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

Phản hồi là một tác vụ, không phải một ảnh:

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "processing",
  "created_at": 1790310979
}

Nếu bạn đang gọi API của Google, thân yêu cầu bạn gửi chính là thân bạn sẽ gửi tới generateContent. Không hỗ trợ gọi trực tiếp /v1beta/models/...:generateContent trên SeedRouter; hãy dùng endpoint này.

Lấy ảnh bằng cách nào?

Truy vấn tác vụ vài giây một lần cho tới khi status là completed hoặc failed. Bằng Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/images/generations",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image",
        "contents": [{"parts": [{"text": "A ceramic teapot on a linen tablecloth, soft window light"}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
        },
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(f"{API}/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Tác vụ đã hoàn tất có URL ảnh trong output.data[0].url, kèm mức sử dụng token. Với "responseModalities": ["TEXT", "IMAGE"], mọi văn bản mô hình viết ra được trả về trong output.text. Hãy tải ảnh về kho lưu trữ của riêng bạn nếu cần dùng lâu dài.

Hết thời gian chờ khi truy vấn không có nghĩa là ảnh đã thất bại. Hãy giữ ID tác vụ và kiểm tra lại; gửi một yêu cầu mới đồng nghĩa với trả tiền cho ảnh thứ hai.

Chỉnh sửa ảnh hoặc dùng ảnh tham chiếu thế nào?

Thêm các phần fileData bên cạnh văn bản. Mỗi phần là một URL công khai kèm kiểu MIME của nó:

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "Turn this photo into a watercolor painting. Keep the composition."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

Nano Banana 2 nhận tối đa 14 tham chiếu mỗi yêu cầu: ảnh, video hoặc PDF, mỗi tệp dưới 50 MB. Tham chiếu phải là URL; không chấp nhận inlineData base64. Nếu không tải được một URL, tác vụ thất bại và không bị tính phí. Để chỉnh sửa tiếp, hãy gửi các lượt trước đó dưới dạng mục user và model rồi kết thúc bằng một lượt user mới.

Những thiết lập nào quan trọng nhất?

Thiết lậpTác dụng
imageConfig.imageSize512, 1K, 2K hoặc 4K; mặc định 1K
imageConfig.aspectRatio14 tỷ lệ từ 1:8 đến 8:1; nếu bỏ qua thì theo tham chiếu đầu tiên
responseModalities["IMAGE"] để chỉ nhận ảnh, ["TEXT", "IMAGE"] để nhận thêm văn bản
systemInstructionCác quy tắc cố định, chẳng hạn phong cách riêng của thương hiệu
seedDùng lại để có kết quả gần với lần trước
mediaResolutionSố token mà mỗi tham chiếu sử dụng; càng thấp càng rẻ trên Official

Tài liệu Nano Banana 2 API liệt kê mọi trường và giới hạn. Các trường không xác định bị từ chối trước khi có bất kỳ khoản phí nào, và Google Search grounding (tools) chưa được hỗ trợ.

Làm sao để một coding agent dùng Nano Banana 2 API?

Một coding agent như Claude Code, Codex hay Cursor có thể gọi API bằng một lệnh shell hoặc một script ngắn. SeedRouter không cung cấp MCP server hay skill đóng gói sẵn; prompt này là toàn bộ phần tích hợp. Hãy export khóa trước, rồi dán vào:

Use the SeedRouter API to generate a Nano Banana 2 image for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, setting, style, what the image is for]
Size: [512 | 1K | 2K | 4K]    Aspect ratio: [e.g. 1:1, 16:9, 9:16]
References: [public image URLs, or none]

Send POST https://api.seedrouter.ai/v1/images/generations with
{"model": "gemini-3.1-flash-image",
 "contents": [{"parts": [{"text": "..."}, {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://..."}}]}],
 "generationConfig": {"responseModalities": ["IMAGE"],
   "imageConfig": {"aspectRatio": "...", "imageSize": "..."}}}
Accepted top-level fields: model, contents, systemInstruction, safetySettings,
generationConfig. References must be fileData URLs (up to 14), never base64.
Do not add tools or any other field.

Before sending, show me the request body and wait for my approval: each
request is charged. Then poll GET https://api.seedrouter.ai/v1/tasks/{id}
every 3 seconds until status is completed or failed. If polling times out,
keep checking the same task; never resubmit. Save output.data[0].url into
./images/ and tell me the file path.

Bước phê duyệt rất quan trọng: agent tiêu số dư của bạn, nên nó không bao giờ được tự ý gửi yêu cầu.

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

Làm sao để lấy khóa API Nano Banana 2?

Đăng nhập, mở trang khóa API và tạo một khóa. Cùng một khóa dùng được cho Nano Banana 2, Nano Banana Pro, Nano Banana 2 Lite và các mô hình khác trên SeedRouter.

Nano Banana 2 API có hỗ trợ yêu cầu hàng loạt không?

Hãy gửi một yêu cầu cho mỗi ảnh và truy vấn các tác vụ song song. Mỗi yêu cầu trả về một ảnh, và mỗi tác vụ được tính phí riêng.

Cần xử lý những lỗi nào?

Mã 400 nghĩa là thân yêu cầu vi phạm một quy tắc, chẳng hạn một trường không xác định hoặc một kích thước không được hỗ trợ, và không có gì bị tính phí. Tác vụ kết thúc failed có kèm thông báo lỗi và cũng không bị tính phí. Hướng dẫn lỗi liệt kê mọi mã lỗi và khi nào nên thử lại.

Gửi yêu cầu đầu tiên

Hãy tạo khóa, nạp một khoản nhỏ và chạy ví dụ Python ở trên, hoặc thử cùng yêu cầu đó mà không cần code trong playground Nano Banana 2. Với prompt phức tạp, hãy đổi mô hình thành gemini-3-pro-image để dùng Nano Banana Pro.

Hướng dẫn liên quan