Nano Banana 2 (Gemini 3.1 Flash Image)

Nano Banana 2 là mô hình Gemini 3.1 Flash Image của Google. Hãy gửi thân yêu cầu generateContent của Google kèm trường model, giữ lại ID tác vụ được trả về, rồi truy vấn tác vụ đó để lấy ảnh đã hoàn thành. Ảnh tham chiếu được đặt trong contents dưới dạng URL fileData.

ID mô hình

Cả hai ID nhận cùng tham số. Xem giá hiện tại trên trang mô hình.

Ví dụ nhanh

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"}
    }
  }'

Endpoint

POST https://api.seedrouter.ai/v1/images/generations

Thân yêu cầu là yêu cầu generateContent của Google với một bổ sung duy nhất: model, vì endpoint này không chứa tên mô hình trong đường dẫn. Phản hồi chứa ID tác vụ, không phải ảnh đã hoàn thành. Hãy giữ khóa API trong mã phía máy chủ. Không hỗ trợ gọi trực tiếp /v1beta/models/...:generateContent; hãy dùng endpoint này.

Tham số

Danh mục an toàn: HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT. Ngưỡng: BLOCK_NONE, BLOCK_ONLY_HIGH, BLOCK_MEDIUM_AND_ABOVE, BLOCK_LOW_AND_ABOVE, OFF.

Các trường không xác định sẽ bị từ chối. Chưa hỗ trợ: Google Search grounding (tools) và nội dung được lưu đệm; thinkingLevel không được ghi trong tài liệu của mô hình này. Không chấp nhận inlineData; hãy truyền media dưới dạng URL fileData. responseFormat.image.delivery chỉ nhận INLINE: ảnh hoàn thành luôn được trả về dưới dạng URL được lưu trữ.

Kích thước đầu ra

Các tỷ lệ khung hình khác giữ nguyên số token; ví dụ 16:9 ở 1K là 1376×768.

Các chế độ

Không có tham số chế độ riêng hay endpoint chỉnh sửa riêng.

Để tiếp tục một cuộc hội thoại, hãy dựng lại lượt model từ output.parts của tác vụ trước, theo đúng thứ tự: một phần văn bản trở thành {"text": ..., "thoughtSignature": ...} và một phần hình ảnh trở thành {"fileData": {"mimeType": "image/<output_format>", "fileUri": <data[image].url>}, "thoughtSignature": ...}. Giữ nguyên từng thoughtSignature đúng như khi được trả về: đó là URL của chữ ký mà chúng tôi lưu giúp bạn (chữ ký của một ảnh 4K nặng vài megabyte), và chúng tôi khôi phục nó trước khi yêu cầu đến mô hình. Chỉ chấp nhận chữ ký từ kết quả tác vụ của chính bạn.

Chỉnh sửa với ảnh tham chiếu

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"}}
      ]
    }]
  }'

Hãy thay URL ví dụ bằng ảnh của bạn mà hệ thống truy cập được.

Đầu vào media

API này chỉ nhận tham chiếu bằng URL. Không chấp nhận inlineData base64, URL data: và tải lên dạng multipart. Playground tải các tệp đã chọn lên kho lưu trữ trước, rồi mới gửi URL của chúng.

Tham chiếu phải là URL HTTP(S) công khai, mỗi tệp nhỏ hơn 50 MB và tổng cộng không quá 100 MB: ảnh (image/png, image/jpeg, image/webp, image/heic, image/heif), video (video/mp4, video/mpeg, video/mov, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp) hoặc tài liệu PDF (application/pdf). mimeType phải khớp với tệp. URL được tải về trong lúc xử lý; ảnh không truy cập được sẽ khiến tác vụ thất bại, và tác vụ thất bại không bị tính phí.

Các yếu tố chi phí

Hãy xem phần giá của mô hình để biết biểu phí hiện tại. gemini-3.1-flash-image tính một mức giá cố định cho mỗi ảnh được giao, bất kể kích thước hay prompt. gemini-3.1-flash-image-official tính theo mức sử dụng: token đầu vào (văn bản và ảnh tham chiếu), token đầu ra văn bản và suy luận, và token đầu ra hình ảnh, mỗi loại một đơn giá riêng. Kích thước ảnh là yếu tố chính; xem bảng ở trên.

Hãy xem chi phí cuối cùng trong lịch sử sử dụng của tài khoản. Tác vụ thất bại không bị tính phí.

Lược đồ đầu ra

Khi gửi, API trả về một tham chiếu tác vụ:

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

Truy vấn tác vụ

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Hãy truy vấn vài giây một lần cho đến khi status là completed hoặc failed. Hết thời gian mạng trong lúc truy vấn không có nghĩa là việc tạo ảnh đã thất bại: hãy giữ ID tác vụ và tiếp tục kiểm tra. Đừng tạo tác vụ khác chỉ để xem tiến độ.

Ví dụ truy vấn đầy đủ

Hãy chạy đoạn này sau ví dụ gửi bằng Python ở trên.

import time

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        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

{
  "id": "task_...",
  "model": "gemini-3.1-flash-image",
  "status": "completed",
  "created_at": 1790310979,
  "finished_at": 1790311001,
  "output": {
    "created": 1790310999,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.jpg"}],
    "output_format": "jpeg",
    "usage": {
      "input_tokens": 27,
      "output_tokens": 1525,
      "total_tokens": 1552,
      "output_tokens_details": {"image_tokens": 1120, "text_tokens": 405, "reasoning_tokens": 0}
    }
  }
}

Không hỗ trợ streaming (streamGenerateContent); kết quả được giao qua tác vụ.

Lỗi

Những yêu cầu bị từ chối trước khi tác vụ được tạo sẽ trả về lỗi HTTP kèm đối tượng error. Tác vụ thất bại sau khi đã được tiếp nhận sẽ trả về HTTP 200 khi truy vấn, kèm status: "failed" và một đối tượng error. Ảnh bị bộ lọc an toàn của mô hình chặn sẽ thất bại với content_policy_violation; phản hồi không có ảnh sẽ thất bại với no_output.

Hãy xem danh mục lỗi dùng chung để biết mã lỗi, mã trạng thái HTTP và hướng dẫn thử lại.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

Nếu chính lần gửi bị hết thời gian chờ, hãy kiểm tra lịch sử tác vụ trước khi gửi lại: yêu cầu đầu tiên có thể đã được tiếp nhận.

Mẹo

• Hãy mô tả chủ thể, bối cảnh, ánh sáng và phong cách bằng câu hoàn chỉnh.
• Khi chỉnh sửa, hãy nêu rõ phần cần thay đổi và phần phải giữ nguyên.
• Dùng 512 hoặc 1K cho bản nháp, và 2K hoặc 4K cho ảnh hoàn chỉnh.
• Hãy lưu ảnh trả về vào kho lưu trữ của riêng bạn nếu cần bản sao lâu dài.

Liên quan

• Playground và bảng giá Nano Banana 2
• Tải OpenAPI
• Markdown có thể sao chép