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).
Phạm vi áp dụng
Trang này giới thiệu các mô hình hình ảnh Grok Imagine. Với mô hình video, xem Grok Video API.
Chọn giao diện
Các mô hình hình ảnh Grok dùng giao diện tương thích OpenAI Images:
| Mục đích | Phương thức | Điểm cuối |
|---|---|---|
| Tạo ảnh từ văn bản | POST | /v1/images/generations |
| Chỉnh sửa hình ảnh (tạo ảnh từ ảnh) | POST | /v1/images/edits |
Không hỗ trợ /v1/chat/completions và /v1/responses. Ảnh tham chiếu chỉ có thể truyền qua /v1/images/edits, nếu đặt trong /v1/images/generations sẽ bị bỏ qua.
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í |
|---|---|---|---|---|
grok-imagine-image | 1K (mặc định) / 2Kaspect_ratio + resolution | tối đa 3 (data URI / URL công khai / tệp cục bộ) | tối đa 10 | theo ảnh |
grok-imagine-image-2.0 | 1K (mặc định) / 2Kaspect_ratio + resolution | tối đa 3 (data URI / URL công khai / tệp cục bộ) | tối đa 10 | theo ảnh |
grok-imagine-image-quality | 1K (mặc định) / 2Kaspect_ratio + resolution | tối đa 3 (data URI / URL công khai / tệp cục bộ) | tối đa 10 | theo ảnh |
grok-imagine-editGiống grok-imagine-image-quality | 1K (mặc định) / 2Kaspect_ratio + resolution | tối đa 3 (data URI / URL công khai / tệp cục bộ) | tối đa 10 | theo ảnh |
Tỷ lệ khung hình hỗ trợ: auto (mặc định) / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 2:1 / 1:2 / 19.5:9 / 9:19.5 / 20:9 / 9:20 / 21:9 / 5:2
| Mô hình | quality | response_format |
|---|---|---|
grok-imagine-image | Không hỗ trợ | b64_json / url |
grok-imagine-image-2.0 | low / medium / auto | b64_json / url |
grok-imagine-image-quality | Không hỗ trợ | b64_json / url |
grok-imagine-edit | Không hỗ trợ | b64_json / url |
- Cả bốn mô hình đều có thể tạo ảnh từ văn bản và chỉnh sửa ảnh.
grok-imagine-editvàgrok-imagine-image-qualitylà cùng một mô hình, kết quả đầu ra như nhau.- Tham số
qualitychỉ có tác dụng vớigrok-imagine-image-2.0. - Tính phí theo số ảnh trả về thành công, không phụ thuộc độ phân giải hay số lượng ảnh tham chiếu.
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.
Xác thực
Authorization: Bearer $API_KEY
Content-Type: application/jsonTỷ lệ khung hình và độ phân giải
aspect_ratio: xem bảng khả năng ở trên. Mặc định làauto, mô hình chọn khung hình dựa theo prompt, cùng một prompt mỗi lần có thể cho tỷ lệ khác nhau; khi cần kích thước cố định, hãy truyền rõ giá trị.resolution:1k(mặc định) hoặc2k, không hỗ trợ 4K.
Kích thước pixel đầu ra của từng mức (giống nhau cho cả bốn mô hình):
| Tỷ lệ | 1K | 2K |
|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 |
| 16:9 | 1280x720 | 2816x1584 |
| 9:16 | 720x1280 | 1584x2816 |
| 4:3 | 1152x864 | 2368x1776 |
| 3:4 | 864x1152 | 1776x2368 |
| 3:2 | 1248x832 | 2496x1664 |
| 2:3 | 832x1248 | 1664x2496 |
| 2:1 | 1408x704 | 2912x1456 |
| 1:2 | 704x1408 | 1456x2912 |
| 19.5:9 | 1248x576 | 2912x1344 |
| 9:19.5 | 576x1248 | 1344x2912 |
| 20:9 | 1280x576 | 3200x1440 |
| 9:20 | 576x1280 | 1440x3200 |
| 21:9 | 1568x672 | 3136x1344 |
| 5:2 | 1600x640 | 3200x1280 |
- Đầu ra 1K là JPEG, đầu ra 2K là PNG, không thể thay đổi qua
output_format. - Cũng có thể dùng
sizetheo thói quen của OpenAI (ví dụ1024x1024), hệ thống sẽ tự quy đổi: cạnh dài không vượt quá 1024 thì theo1k, vượt quá thì theo2k, tỷ lệ lấy giá trị được hỗ trợ gần nhất, vì vậy kích thước pixel trả về không nhất thiết bằngsizeđã yêu cầu.1536x1024,1792x1024đều xuất ra theo2k. - Khi truyền đồng thời
sizevàaspect_ratio/resolution, sẽ ưu tiênaspect_ratio/resolution.
Tạo ảnh từ văn bản
curl https://api.88api.ai/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "Đường phố Tokyo trong đêm mưa dưới ánh đèn neon, chất điện ảnh, nhiếp ảnh chân thực",
"aspect_ratio": "16:9",
"resolution": "2k",
"n": 1
}'Tham số yêu cầu
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
model | string | Có | Tên mô hình. |
prompt | string | Có | Mô tả hình ảnh, không được để trống. Nên giữ trong vòng vài nghìn ký tự. |
aspect_ratio | string | Không | Tỷ lệ khung hình, mặc định auto. |
resolution | string | Không | 1k (mặc định) hoặc 2k. |
n | integer | Không | Số lượng ảnh, từ 1 đến 10, mặc định 1. |
response_format | string | Không | b64_json (mặc định) hoặc url. Khi chọn url sẽ trả về liên kết ảnh của 88API. |
quality | string | Không | Chỉ grok-imagine-image-2.0: low, medium, auto (mặc định; khi tạo ảnh tương đương low, khi chỉnh sửa tương đương medium). medium tạo ảnh chậm hơn. |
Các tham số như style, seed, negative_prompt, background, output_format, stream sẽ bị bỏ qua.
Ví dụ phản hồi
{
"created": 1760000000,
"data": [
{ "b64_json": "/9j/4AAQ...", "mime_type": "image/jpeg" }
]
}Phản hồi không chứa revised_prompt.
Chỉnh sửa hình ảnh
Yêu cầu JSON (khuyến nghị, hỗ trợ nhiều ảnh tham chiếu)
Một ảnh tham chiếu dùng image, nhiều ảnh tham chiếu dùng mảng images, tối đa 3 ảnh:
curl https://api.88api.ai/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image-quality",
"prompt": "Đưa người trong ảnh thứ nhất vào khung cảnh của ảnh thứ hai, giữ nguyên ngoại hình của người đó",
"images": [
"data:image/png;base64,...",
"https://example.com/scene.jpg"
],
"resolution": "2k"
}'- Ảnh tham chiếu có thể là Data URI hoặc URL công khai tải trực tiếp được. Base64 phải có tiền tố
data:image/...;base64,. - Hỗ trợ JPG, PNG, WebP, không hỗ trợ GIF, BMP.
- Đừng viết
imagethành mảng, cũng đừng truyền đồng thờiimagevàimages. - Ảnh tham chiếu được đánh số theo thứ tự truyền vào, trong prompt có thể gọi là «ảnh thứ nhất», «ảnh thứ hai».
- Khi không truyền tỷ lệ, tỷ lệ đầu ra theo ảnh tham chiếu đầu tiên, độ phân giải mặc định là
1k; có thể ghi đè bằngaspect_ratio,resolution.
Tải lên multipart (một ảnh)
Tệp cục bộ cũng có thể tải lên bằng multipart, nhưng mỗi lần chỉ được một ảnh, mỗi tệp không vượt quá 20 MB:
curl https://api.88api.ai/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-imagine-image" \
-F "image=@input.png" \
-F "prompt=Thay nền thành cảnh hoàng hôn bên bờ biển" \
-F "aspect_ratio=1:1"Khi cần nhiều ảnh tham chiếu, hãy dùng yêu cầu JSON.
Giới hạn
- Không hỗ trợ vẽ lại cục bộ bằng
mask, mặt nạ được truyền vào sẽ bị bỏ qua. - Không hỗ trợ đầu ra dạng luồng và lấy kết quả bất đồng bộ.
- Ảnh đầu ra có kèm thông tin xác thực nội dung C2PA (đánh dấu là do AI tạo), không có hình mờ hiển thị.
Lỗi thường gặp
| Tình huống | HTTP | Thông tin trả về |
|---|---|---|
| Gọi giao diện hội thoại hoặc Responses | 400 | <模型> 是生图模型,不支持 <接口> 接口。请改用:POST /v1/images/generations, POST /v1/images/edits (mô hình là mô hình tạo ảnh, không hỗ trợ giao diện này) |
| Tỷ lệ không được hỗ trợ | 400 | 不支持的图片比例。支持:… (tỷ lệ ảnh không được hỗ trợ, kèm danh sách tỷ lệ hỗ trợ) |
Độ phân giải không được hỗ trợ (ví dụ 4k) | 400 | 不支持的图片分辨率。resolution 仅支持 1k 或 2k,请使用小写格式。 (resolution chỉ hỗ trợ 1k hoặc 2k, viết thường) |
n ngoài khoảng 1 đến 10, prompt trống, truyền đồng thời image và images, multipart truyền nhiều ảnh | 400 | 上游拒绝了请求参数(invalid-argument),请检查模型名、调用接口和请求参数 (thượng nguồn từ chối tham số yêu cầu, hãy kiểm tra tên mô hình, giao diện gọi và tham số) |
| Định dạng ảnh tham chiếu không được hỗ trợ, Base64 thiếu tiền tố, URL không tải được | 400 | Thông báo lỗi liên quan đến ảnh tham chiếu |
| Hơn 3 ảnh tham chiếu | 502 | Upstream request failed |
| Không vượt qua kiểm duyệt nội dung | 400 | 图片生成未通过内容安全审核,请修改提示词或参考素材后重试。 (tạo ảnh không vượt qua kiểm duyệt an toàn nội dung, hãy sửa prompt hoặc tư liệu tham chiếu 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í.