88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Image

API mô hình hình ảnh Gemini

Định dạng yêu cầu theo giao thức tương thích OpenAI và giao thức gốc Gemini, tỷ lệ khung hình, độ phân giải và ảnh tham chiếu cho Gemini 3.1 Flash Image, Nano Banana 2.1 và Gemini 3 Pro Image.

Phạm vi áp dụng

Trang này giới thiệu các mô hình hình ảnh Gemini. Với mô hình hình ảnh OpenAI, xem API mô hình hình ảnh OpenAI; với mô hình hình ảnh Grok, xem API mô hình hình ảnh Grok.

Khác biệt chính

Mô hình hình ảnh Gemini không phải mô hình của OpenAI Images API. Hãy dùng /v1/chat/completions hoặc giao diện gốc của Gemini /v1beta/models/{model}:generateContent, không gửi tới /v1/images/generations hoặc /v1/images/edits.

Mô hình và khả năng

Mô hìnhĐộ phân giảiẢnh tham chiếuSố ảnh mỗi yêu cầuTính phí
gemini-3.1-flash-image1K (mặc định) / 2K / 4K
image_config
tối đa 14 (data URI / URL công khai)luôn 1theo yêu cầu
gemini-nano-banana-2.11K (mặc định) / 2K / 4K
image_config
tối đa 6 (data URI / URL công khai)luôn 1theo yêu cầu
gemini-3-pro-image1K (mặc định) / 2K / 4K
image_config
tối đa 14 (data URI / URL công khai)luôn 1theo yêu cầu

Tỷ lệ khung hình hỗ trợ: 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9

  • Cả ba mô hình đều tính phí theo lượt gọi, giá không phụ thuộc độ phân giải hay số lượng ảnh tham chiếu.
  • Mỗi yêu cầu chỉ trả về 1 ảnh, n và candidateCount không có tác dụng; cần nhiều ảnh thì gửi nhiều yêu cầu song song.
  • Với gemini-nano-banana-2.1, nên truyền tối đa 6 ảnh tham chiếu mỗi lần, phần vượt quá có thể không được sử dụng.

Mô hình thực tế có thể dùng được căn cứ theo danh sách mô hình hiển thị trong bảng điều khiển.

Giao thức được hỗ trợ

Giao thứcĐiểm cuốiĐịnh dạng thân yêu cầuTình huống sử dụng
Giao thức tương thích OpenAI (khuyến nghị)POST /v1/chat/completionsmodel + messagesOpenAI SDK, client hợp nhất và phần lớn ứng dụng
Giao thức gốc GeminiPOST /v1beta/models/{model}:generateContentcontents + generationConfigDùng trực tiếp Gemini SDK hoặc cần các trường gốc

Xác thực

Giao thức tương thích OpenAI dùng:

Authorization: Bearer $API_KEY
Content-Type: application/json

Giao thức gốc Gemini cũng có thể dùng header x-goog-api-key theo thói quen của client Gemini, giá trị điền vào vẫn là token 88API của bạn. Không ghi khóa thật vào mã frontend, log hoặc ví dụ công khai.

Tỷ lệ khung hình và độ phân giải

Tỷ lệ khung hình và độ phân giải được thiết lập qua image_config:

  • aspect_ratio: xem bảng khả năng ở trên.
  • image_size: 1K (mặc định), 2K, 4K; hãy dùng chữ K viết hoa.

Kích thước pixel đầu ra của từng mức:

Tỷ lệ1K2K4K
1:11024x10242048x20484096x4096
2:3848x12641696x25283392x5056
3:21264x8482528x16965056x3392
3:4896x12001792x24003584x4800
4:31200x8962400x17924800x3584
4:5928x11521856x23043712x4608
5:41152x9282304x18564608x3712
9:16768x13761536x27523072x5504
16:91376x7682752x15365504x3072
21:91584x6723168x13446336x2688
  • Khi không truyền tỷ lệ, mô hình sẽ chọn khung hình dựa theo prompt; khi có ảnh tham chiếu, mặc định theo tỷ lệ của ảnh tham chiếu đầu tiên. Khi cần kích thước cố định, hãy truyền rõ aspect_ratio.
  • Đầu ra có thể là JPEG hoặc PNG, hãy lưu theo kiểu MIME được trả về, đừng mặc định phần mở rộng.

Giao thức tương thích OpenAI (khuyến nghị)

Tạo ảnh từ văn bản

curl https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "messages": [
      {
        "role": "user",
        "content": "Tạo một bức ảnh chú mèo cam ngồi bên cửa sổ, ánh sáng tự nhiên buổi chiều, phong cách nhiếp ảnh chân thực"
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "16:9",
          "image_size": "2K"
        }
      }
    }
  }'

Cách viết image_config

Tỷ lệ khung hình và độ phân giải phải đặt trong extra_body.google.image_config, tên trường là aspect_ratio, image_size (viết bằng dấu gạch dưới). image_config, aspect_ratio, size đặt ở cấp cao nhất của yêu cầu sẽ bị bỏ qua; viết kiểu camelCase như imageConfig, aspectRatio sẽ bị từ chối.

Kèm ảnh tham chiếu

curl https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Dựa theo nhân vật trong ảnh thứ nhất, tạo một tấm poster phim với cùng nhân vật đó" },
          { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
        ]
      }
    ],
    "extra_body": {
      "google": { "image_config": { "aspect_ratio": "2:3", "image_size": "2K" } }
    }
  }'
  • image_url.url có thể là Data URI hoặc URL ảnh công khai. Data URI phải có đầy đủ tiền tố kiểu phương tiện, ví dụ data:image/png;base64,....
  • Hỗ trợ PNG, JPEG, WebP, GIF, không hỗ trợ BMP. Mỗi ảnh nên không vượt quá 7 MB.
  • Nhiều ảnh tham chiếu được sắp theo thứ tự, trong prompt có thể gọi là «ảnh thứ nhất», «ảnh thứ hai».

Trường yêu cầu

TrườngKiểuBắt buộcMô tả
modelstringCóTên mô hình hình ảnh Gemini.
messagesarrayCóMảng tin nhắn OpenAI Chat Completions, thường chỉ có một tin nhắn user.
messages[].contentstring hoặc arrayCóVăn bản thuần dùng chuỗi; khi kết hợp văn bản và ảnh tham chiếu thì dùng mảng nội dung.
content[].image_url.urlstringKhôngẢnh tham chiếu, Data URI hoặc URL công khai.
extra_body.google.image_config.aspect_ratiostringKhôngTỷ lệ khung hình.
extra_body.google.image_config.image_sizestringKhông1K, 2K, 4K.

Phản hồi

Ảnh được đặt trong choices[0].message.content dưới dạng ảnh Markdown:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "![image](data:image/jpeg;base64,/9j/4AAQ...)"
      },
      "finish_reason": "stop"
    }
  ]
}

Trích xuất data:<mime>;base64,... từ content là có được ảnh. Đừng phân tích phản hồi như mảng data của /v1/images/generations.

Giao thức gốc Gemini

Tạo ảnh từ văn bản

curl "https://api.88api.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Tạo một bức ảnh chú mèo cam ngồi bên cửa sổ, ánh sáng tự nhiên buổi chiều, phong cách nhiếp ảnh chân thực" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Ảnh tham chiếu

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Dựa theo bức ảnh này, tạo một tấm poster phim với cùng nhân vật đó" },
        { "inlineData": { "mimeType": "image/png", "data": "<BASE64_DATA>" } }
      ]
    }
  ],
  "generationConfig": {
    "imageConfig": { "aspectRatio": "2:3" }
  }
}

Ảnh công khai cũng có thể dùng fileData: { "fileData": { "mimeType": "image/jpeg", "fileUri": "https://..." } }.

Phản hồi

Ảnh nằm ở candidates[0].content.parts[].inlineData, mimeType là kiểu ảnh, data là Base64.

Truyền luồng và thời gian chờ

Có thể dùng stream: true, nhưng ảnh sẽ được trả về một lần trong một sự kiện, không có xem trước từng phần. Nên dùng yêu cầu không truyền luồng và đặt thời gian chờ của client từ 5 phút trở lên: ảnh 4K thường mất 30 đến 60 giây, giờ cao điểm sẽ lâu hơn.

Đừng gửi yêu cầu như thế này

# Sai: mô hình hình ảnh Gemini không dùng đường dẫn OpenAI Images API
curl https://api.88api.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "Một chú mèo cam"
  }'

Yêu cầu kiểu này sẽ trả về 请使用 Gemini 原生接口调用 / please use the Gemini native API. Hãy chuyển sang định dạng Chat Completions hoặc generateContent gốc như trong trang này.

Lỗi thường gặp

LỗiNguyên nhân
请使用 Gemini 原生接口调用 (hãy dùng giao diện gốc Gemini)Yêu cầu bị gửi tới /v1/images/*.
extra_body.google.imageConfig is not supported, use extra_body.google.image_config insteadimage_config bị viết theo kiểu camelCase.
mime type is not supported by GeminiĐịnh dạng ảnh tham chiếu không được hỗ trợ, ví dụ BMP.
failed to download fileKhông tải được URL ảnh tham chiếu, hãy xác nhận liên kết có thể truy cập công khai.
Thông báo không vượt qua kiểm duyệt nội dungPrompt hoặc ảnh tham chiếu không vượt qua kiểm duyệt an toàn, hoặc mô hình chỉ trả lời bằng văn bản mà không tạo ảnh; hãy điều chỉnh prompt rồi thử lại.

Các yêu cầu thất bại nêu trên không bị tính phí.