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ếu | Số ảnh mỗi yêu cầu | Tính phí |
|---|---|---|---|---|
gemini-3.1-flash-image | 1K (mặc định) / 2K / 4Kimage_config | tối đa 14 (data URI / URL công khai) | luôn 1 | theo yêu cầu |
gemini-nano-banana-2.1 | 1K (mặc định) / 2K / 4Kimage_config | tối đa 6 (data URI / URL công khai) | luôn 1 | theo yêu cầu |
gemini-3-pro-image | 1K (mặc định) / 2K / 4Kimage_config | tối đa 14 (data URI / URL công khai) | luôn 1 | theo 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,
nvàcandidateCountkhô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ầu | Tình huống sử dụng |
|---|---|---|---|
| Giao thức tương thích OpenAI (khuyến nghị) | POST /v1/chat/completions | model + messages | OpenAI SDK, client hợp nhất và phần lớn ứng dụng |
| Giao thức gốc Gemini | POST /v1beta/models/{model}:generateContent | contents + generationConfig | Dù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/jsonGiao 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ữKviết hoa.
Kích thước pixel đầu ra của từng mức:
| Tỷ lệ | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 2:3 | 848x1264 | 1696x2528 | 3392x5056 |
| 3:2 | 1264x848 | 2528x1696 | 5056x3392 |
| 3:4 | 896x1200 | 1792x2400 | 3584x4800 |
| 4:3 | 1200x896 | 2400x1792 | 4800x3584 |
| 4:5 | 928x1152 | 1856x2304 | 3712x4608 |
| 5:4 | 1152x928 | 2304x1856 | 4608x3712 |
| 9:16 | 768x1376 | 1536x2752 | 3072x5504 |
| 16:9 | 1376x768 | 2752x1536 | 5504x3072 |
| 21:9 | 1584x672 | 3168x1344 | 6336x2688 |
- 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.urlcó 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ường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
model | string | Có | Tên mô hình hình ảnh Gemini. |
messages | array | Có | Mảng tin nhắn OpenAI Chat Completions, thường chỉ có một tin nhắn user. |
messages[].content | string hoặc array | Có | 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.url | string | Không | Ảnh tham chiếu, Data URI hoặc URL công khai. |
extra_body.google.image_config.aspect_ratio | string | Không | Tỷ lệ khung hình. |
extra_body.google.image_config.image_size | string | Không | 1K, 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": ""
},
"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ỗi | Nguyê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 instead | image_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 file | Khô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 dung | Prompt 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í.
API mô hình hình ảnh OpenAI
Giao diện, kích thước, mức chất lượng, ảnh tham chiếu và nền trong suốt của các mô hình hình ảnh gpt-image-2, gpt-image-2.5 và dòng az-gpt-image.
API mô hình hình ảnh Grok
Giao diện tạo ảnh từ văn bản và chỉnh sửa ảnh, tỷ lệ khung hình, độ phân giải, ảnh tham chiếu và mã lỗi của các mô hình hình ảnh Grok Imagine (grok-imagine-image, 2.0, quality, edit).