Nano Banana (mô hình hình ảnh Gemini)

Thông tin chung

• Base URL: https://api.routeapi.ai
• Xác thực: Authorization: Bearer $ROUTEAPI_KEY với API Key bắt đầu bằng sk- (tạo tại trang API Key). Khóa quản lý bắt đầu bằng rat_ không thể gọi mô hình.
• Định dạng lỗi: {"error": {"message": "...", "type": "...", "code": "..."}}; ý nghĩa mã trạng thái xem tại Lỗi thường gặp.

Mô hình hình ảnh Gemini đang bán: gemini-3.1-flash-image-preview, gemini-3-pro-image-preview và gemini-3.1-flash-lite-image. Đây là các mô hình tạo hình ảnh do kênh Gemini cung cấp, và có hai cách gọi (xem supported_endpoint_types trong Mô hình để biết danh sách chính xác của từng mô hình):

Đường dẫn	Endpoint	Body bạn gửi
Định dạng hình ảnh OpenAI	POST /v1/images/generations	JSON hình ảnh OpenAI, mô tả tại Định dạng hình ảnh OpenAI
Gemini gốc	POST /v1beta/models/{model}:generateContent	contents + generationConfig của Gemini

Dùng đường dẫn gốc khi client đã nói giao thức Gemini (Google GenAI SDK) và cần kiểm soát đầy đủ responseModalities và imageConfig; dùng /v1/images/generations khi client chỉ hỗ trợ API hình ảnh OpenAI.

Qua /v1/images/generations

Khung yêu cầu, xác thực và body lỗi giống Định dạng hình ảnh OpenAI. RouteAPI chuyển yêu cầu hình ảnh của bạn thành lệnh gọi generateContent của Gemini.

Tham số yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID mô hình hình ảnh Gemini như gemini-3.1-flash-image-preview
prompt	string	Có	Được gửi thành một phần văn bản duy nhất trong lượt user
size	string	Không	Ánh xạ sang generationConfig.imageConfig.aspectRatio (xem bảng dưới)
n	integer	Không	Giá trị lớn hơn 1 được gửi thành generationConfig.candidateCount; 1 hoặc bỏ qua thì không gửi gì
quality, response_format, style, user, watermark	—	Không	Không được chuyển đổi trên đường dẫn này; adapter Gemini bỏ qua chúng

RouteAPI tự điền responseModalities bằng ["TEXT", "IMAGE"], nên qua endpoint này bạn không cần truyền. Cài đặt an toàn lấy từ cấu hình Gemini của nền tảng.

Kích thước sang tỷ lệ khung

Chỉ các giá trị size chính xác sau mới ánh xạ sang tỷ lệ khung:

size	aspectRatio
256x256, 512x512, 1024x1024	1:1
1536x1024	3:2
1024x1536	2:3
1024x1792	9:16
1792x1024	16:9

Giá trị đã chứa : được truyền nguyên như tỷ lệ khung. Mọi giá trị khác (ví dụ 2K hay auto) không gửi imageConfig nào, và mặc định của upstream được áp dụng. Kích thước pixel không được yêu cầu trên đường dẫn này — tỷ lệ khung là cách điều khiển kích thước duy nhất.

Ví dụ yêu cầu

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A nano banana wearing sunglasses, studio product shot",
    "size": "1536x1024"
  }'

Phản hồi

Phản hồi được chuyển thành đối tượng hình ảnh OpenAI; chỉ các phần hình ảnh inline còn lại, mọi văn bản mô hình trả về đều bị loại bỏ.

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

Đường dẫn này không tạo URL — luôn đọc data[].b64_json. Nếu phản hồi không có phần hình ảnh, yêu cầu thất bại với 500; nếu Gemini chặn prompt, yêu cầu thất bại với 400 và lý do bị chặn được ghi vào yêu cầu.

Chú ý

Không dùng /v1/images/edits để gửi ảnh tham chiếu tới mô hình hình ảnh Gemini. Yêu cầu đi theo đường chat văn bản: chỉ prompt được chuyển đổi, image / images / mask bị bỏ qua, và phản hồi là một OpenAI chat completion có nội dung chứa ảnh Markdown, không phải đối tượng images. Hãy gửi yêu cầu gốc bên dưới khi cần đầu vào hình ảnh.

Gọi gốc bằng generateContent

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

Ví dụ:

curl https://api.routeapi.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "x-goog-api-key: $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Draw a cat astronaut on the moon" }] }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Xác thực Gemini

Trên các đường dẫn /v1beta, API Key có thể gửi theo một trong ba cách: x-goog-api-key: $ROUTEAPI_KEY, ?key=$ROUTEAPI_KEY trong query, hoặc Authorization: Bearer $ROUTEAPI_KEY. Nếu có nhiều cách cùng lúc, ?key= và x-goog-api-key được áp dụng thay cho Authorization.

Trường yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
contents	array	Có	Nội dung hội thoại Gemini; ít nhất một phần tử. Vai trò là user và model
generationConfig.responseModalities	array of string	Thực tế bắt buộc	Phải bao gồm IMAGE, nếu không mô hình chỉ trả văn bản
generationConfig.imageConfig	object	Không	Tùy chọn hình ảnh, được truyền tới Gemini. aspectRatio như 1:1, 3:2, 16:9; imageSize như 1K, 2K, 4K. Giá trị chấp nhận tùy mô hình
generationConfig.candidateCount	integer	Không	Số ứng viên; không phải mô hình hình ảnh nào cũng hỗ trợ
safetySettings	array	Không	Cài đặt an toàn Gemini, truyền nguyên
systemInstruction	object	Không	Chỉ dẫn hệ thống; cũng chấp nhận dạng snake_case system_instruction

generationConfig chấp nhận cả camelCase và snake_case cho các trường (ví dụ responseModalities / response_modalities và imageConfig / image_config); nếu cả hai cùng có, snake_case thắng. imageConfig và nội dung của nó được truyền mà không kiểm tra, nên imageSize không được hỗ trợ sẽ do Gemini báo lỗi, không phải RouteAPI.

Ghi chú

Yêu cầu gốc không bị viết lại như đường dẫn OpenAI: RouteAPI không tự thêm responseModalities. Bỏ qua trường này là nguyên nhân phổ biến nhất khiến yêu cầu trả về văn bản mà không có hình ảnh.

Đầu vào hình ảnh

Để chỉnh sửa hoặc tham chiếu một hình ảnh, thêm một phần hình ảnh inline bên cạnh văn bản:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Repaint this photo as a watercolor illustration" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA..."
          }
        }
      ]
    }
  ],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

inlineData mang byte hình ảnh Base64, được truyền nguyên tới Gemini. Với tệp đã tải lên Google, phần fileData.fileUri gốc cũng thuộc cấu trúc được truyền. Nếu client dùng định dạng chat OpenAI, các phần image_url được tải xuống phía máy chủ và chuyển thành phần inline trước khi tới Gemini.

Truyền phát

Truyền phát được chọn bằng tham số ?alt=sse, không phải bằng tên action: khi có nó, action upstream trở thành streamGenerateContent và phản hồi là luồng server-sent events của Gemini. Mỗi phần có cấu trúc candidates[].content.parts chuẩn. Dùng khi muốn nhận hình ảnh dần dần; nếu không, :generateContent trả toàn bộ phản hồi trong một body.

Phản hồi

Đường dẫn gốc trả nguyên cấu trúc phản hồi của Gemini:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Here is the image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1132
  }
}

Đọc hình ảnh từ parts[].inlineData; thường đi kèm phần văn bản. Khi Gemini chặn yêu cầu, promptFeedback.blockReason được đặt và candidates rỗng.

Tính phí

Mô hình hình ảnh Gemini tính phí theo token: hình ảnh tạo ra được tính là token đầu ra theo giá đầu ra, còn prompt và ảnh tham chiếu tính là token đầu vào. Giá hiện tại xem tại Giá mô hình và trang chi tiết mô hình.

Bước tiếp theo

• Định dạng hình ảnh OpenAI — khung /v1/images dùng chung và hành vi chỉnh sửa.
• Seedream — kích thước và ngữ nghĩa chỉnh sửa của ByteDance Seedream.
• Mô hình — tìm mô hình hình ảnh và xác nhận hỗ trợ image-generation.
• Giá mô hình — tính phí theo token và theo ảnh.