API MiniMax H3-Image tạo và chỉnh sửa hình ảnh qua hai endpoint REST: POST /v1/images/generations cho text-to-image và POST /v1/images/edits để chỉnh sửa với 1 đến 16 ảnh tham chiếu. Bạn gửi khóa Bearer, model ID MiniMax-H3-Image (hoặc MiniMax-H3-Image-Highspeed), một prompt và kích thước, rồi nhận về URL ảnh hoặc dữ liệu base64. API này chạy trên cùng nền tảng nhà phát triển MiniMax với MiniMax M3 API. Kết quả đầu ra có thể lên tới khoảng 16 megapixel mà không cần upscaler.
Dưới đây là: cách lấy khóa, các trường quan trọng, chỉnh sửa ảnh, bảng giá kèm ưu đãi ra mắt, và một bài kiểm tra chạy bằng agent với Apidog CLI. Còn mới với model này? Hãy bắt đầu với MiniMax H3-Image là gì.
MiniMax H3-Image API là gì?
MiniMax H3-Image API là endpoint do MiniMax vận hành cho model mã nguồn mở H3-Image, xử lý cả text-to-image và chỉnh sửa ảnh đa tham chiếu trong cùng một checkpoint. Nó được phục vụ tại https://api.minimax.io, nhận yêu cầu JSON, và tương thích với các lệnh images.generate và images.edit của OpenAI SDK, nên hầu hết mã hình ảnh hiện có chỉ cần đổi base URL và tên model.
Trọng số của model cũng được công khai: model card trên Hugging Face liệt kê một diffusion transformer 33,1 tỷ tham số theo giấy phép MiniMax-H3-Image Community License. Tự host cần khoảng 69 GB cho checkpoint cùng một text encoder 66,7 GB, nên API là lựa chọn thực tế cho đa số đội ngũ.
Phần dịch vụ đám mây, theo tài liệu tham khảo API của MiniMax ngày 2026-11-11:
| Mục | Giá trị |
|---|---|
| Base URL | https://api.minimax.io |
| Model IDs | MiniMax-H3-Image, MiniMax-H3-Image-Highspeed (cùng tham số và giới hạn) |
| Text-to-image | POST /v1/images/generations |
| Chỉnh sửa ảnh | POST /v1/images/edits, 1 đến 16 ảnh tham chiếu |
| Số ảnh mỗi yêu cầu | n từ 1 đến 10 |
| Định dạng đầu ra | jpeg (mặc định), png, webp |
| Kiểu trả về | url (mặc định) hoặc b64_json |
| Thời gian chờ tối đa của server | 600 giây |
Lấy khóa API MiniMax của bạn
- Đăng nhập tại nền tảng nhà phát triển MiniMax.
- Mở Quản lý tài khoản, sau đó API Keys, và tạo một khóa.
- Nạp số dư. Một yêu cầu không có tiền sẽ thất bại với HTTP 402 và mã lỗi
1008(số dư không đủ). - Xuất khóa để mã của bạn và agent đọc từ biến môi trường, không bao giờ từ tệp bạn commit:
export MINIMAX_API_KEY="your-key-here"
Mọi lệnh gọi đều gửi khóa qua Authorization: Bearer $MINIMAX_API_KEY.
Yêu cầu text-to-image đầu tiên của bạn
Lệnh gọi nhỏ nhất nhưng hữu ích cần model, prompt và hoặc một kích thước cụ thể hoặc một bậc diện tích:
curl https://api.minimax.io/v1/images/generations \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
--max-time 600 \
-d '{
"model": "MiniMax-H3-Image",
"prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
"aspect_ratio": "16:9",
"area": "2K",
"n": 1,
"response_format": "url"
}'
Với OpenAI Python SDK, trỏ base_url về MiniMax và tắt retry:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key=os.environ["MINIMAX_API_KEY"],
timeout=600,
max_retries=0,
)
result = client.images.generate(
model="MiniMax-H3-Image",
prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
size="2720x1536",
response_format="url",
)
for item in result.data:
print(item.url) # None for an image that failed
Dòng max_retries=0 rất quan trọng. Endpoint này không idempotent: server hoàn tất và tính tiền cho một job kể cả khi client của bạn hết thời gian chờ, nên một lần retry tự động sẽ bị tính tiền hai lần. Hãy đặt timeout 600 giây thay vì thế.
Các tham số yêu cầu quan trọng
Bạn kiểm soát kích thước đầu ra theo một trong hai cách, và không thể trộn lẫn.
Pixel chính xác. Đặt size thành WIDTHxHEIGHT, ví dụ 4096x4096. Tổng diện tích phải nằm giữa 655.360 và 20.000.000 pixel, và tỷ lệ khung hình giữa 1:3 và 3:1. Không gửi aspect_ratio hay area ở chế độ này, kể cả dưới dạng auto, nếu không bạn sẽ nhận lỗi 400.
Bậc cộng tỷ lệ. Để size là auto và đặt area (1K, 2K hoặc 4K, mặc định 4K) và aspect_ratio (bất kỳ X:Y nào từ 1:3 đến 3:1). Server sẽ tự tính pixel; 2K ở 16:9 trả về 2720 x 1536.
Các trường khác:
| Trường | Mặc định | Tác dụng |
|---|---|---|
prompt |
bắt buộc | Tối đa 32.000 ký tự |
disable_prompt_enhanced |
false |
Tính năng nâng cấp prompt sẽ viết lại prompt ngắn thành mô tả chi tiết; kết quả được trả về dưới dạng revised_prompt |
n |
1 | 1 đến 10 ảnh |
output_format |
jpeg |
png, jpeg hoặc webp |
output_compression |
95 | 0 đến 100, chỉ dành cho JPEG và WebP |
response_format |
url |
url hoặc b64_json |
stream |
false |
Server-sent events, một sự kiện cho mỗi ảnh hoàn tất, chỉ với url |
Có hai quy tắc dễ khiến người dùng mắc lỗi. Thứ nhất, nếu bạn tắt tính năng nâng cấp prompt, bạn phải cung cấp size chính xác hoặc aspect_ratio rõ ràng; auto sẽ trả về lỗi 400. Thứ hai, b64_json giới hạn tổng diện tích đầu ra: 20.000.000 pixel cho PNG (một ảnh với kích thước bất kỳ) và 80.000.000 cho JPEG hoặc WebP (bốn ảnh 4K hoặc mười ảnh 2K). Với các lô lớn hơn, hãy dùng URL.
Model card cho biết H3-Image hoạt động tốt nhất quanh mức 16 MP: 4096x4096 (1:1), 5472x3072 (16:9) hoặc 6272x2688 (21:9).
Chỉnh sửa ảnh với tối đa 16 ảnh tham chiếu
Chỉnh sửa dùng các trường giống như trên, cộng thêm mảng images. Tham chiếu tới ảnh đầu vào theo vị trí trong prompt (“image 1”, “image 2”):
import os, requests
resp = requests.post(
"https://api.minimax.io/v1/images/edits",
headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
json={
"model": "MiniMax-H3-Image",
"prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
"images": [
{"image_url": "https://example.com/cat.jpg"},
{"image_url": "https://example.com/dog.png"},
],
"size": "auto",
"response_format": "url",
},
timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])
Endpoint này cũng chấp nhận multipart/form-data, đây là thứ OpenAI SDK gửi qua images.edit khi bạn tải tệp lên. Các giới hạn theo tài liệu tham khảo edits:
- 1 đến 16 ảnh định dạng JPG, PNG, WebP, HEIC hoặc HEIF
- Mỗi cạnh từ 128 đến 8.192 pixel, tỷ lệ cạnh dài/ngắn không quá 4:1
- Tổng phần thân yêu cầu tối đa 64 MiB; base64 làm tăng khoảng một phần ba, nên hãy chuyển sang URL công khai cho dữ liệu đầu vào lớn
Đọc phản hồi và xử lý lỗi
Một lệnh gọi thành công trả về một mục data cho mỗi ảnh được yêu cầu, theo thứ tự:
{
"data": [
{"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
{"error": {"code": "1027", "message": "output image failed content safety check"}}
],
"output_format": "jpeg",
"usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
"request_id": "0217..."
}
Ba thói quen giúp tích hợp của bạn đáng tin cậy:
- Kiểm tra từng mục có
errorhay không. Mã HTTP là 200 nếu ít nhất một ảnh thành công, nên 200 không có nghĩa là tất cảnảnh đã được trả về. Nếu mọi ảnh đều thất bại, bạn sẽ nhận 402, 422 hoặc 500 thay vì thế. - Tải URL ngay lập tức. MiniMax cho biết không đảm bảo URL vẫn khả dụng, vì vậy hãy sao chép tệp về nơi lưu trữ của riêng bạn.
- Ghi log
request_id. Đây là trace ID mà bộ phận hỗ trợ sẽ yêu cầu.
Vượt giới hạn tốc độ sẽ trả về 429. Mã 1002 nghĩa là bạn đã vượt giới hạn ảnh mỗi phút, và mỗi yêu cầu được tính là n ảnh, nên một lô 10 ảnh sẽ dùng 10 lượt trong hạn mức của bạn cùng lúc.
Giá MiniMax H3-Image và ưu đãi ra mắt
Thanh toán theo token, và bạn chỉ trả tiền cho các ảnh thành công. Theo trang bảng giá của MiniMax, ghi nhận ngày 2026-11-11:
| Model | Văn bản đầu vào / 1M token | Ảnh đầu vào / 1M token | Ảnh đầu ra / 1M token |
|---|---|---|---|
| MiniMax-H3-Image | $2.30 | $1.50 | $3.80 |
| MiniMax-H3-Image-Highspeed | $2.30 | $3.00 | $7.60 |
MiniMax cũng công bố chi phí ví dụ cho mỗi ảnh của model tiêu chuẩn:
| Nhiệm vụ | Đầu ra | Chi phí ví dụ cho mỗi ảnh |
|---|---|---|
| Text-to-image | 1K (1024 x 1024) | $0.02179 |
| Text-to-image | 2K (2048 x 2048) | $0.02333 |
| Text-to-image | 4K (4096 x 4096) | $0.06879, $0.03439 trong thời gian ưu đãi ra mắt |
Highspeed tốn kém hơn khoảng 1,6 đến 2 lần cho mỗi ảnh ($0.13001 cho 4K, $0.06501 khi được giảm giá). Độ dài prompt ảnh hưởng đến phần chi phí đầu vào, vì vậy hãy coi đây là các con số ước tính.
Ưu đãi ra mắt: đến ngày 17 tháng 11 năm 2026 lúc 16:00 UTC, MiniMax giảm 50% tổng chi phí yêu cầu cho cả hai model khi ảnh được tạo ra có ít nhất 16.600.000 pixel. Một ảnh 4096x4096 (16.777.216 pixel) đủ điều kiện; ảnh 2K thì không. Bạn đang tìm các cách dùng miễn phí? Xem cách dùng MiniMax H3-Image miễn phí.
Cho agent lập trình của bạn kiểm thử bằng Apidog CLI
Các API hình ảnh thường thất bại một cách âm thầm: một mã 200 nhưng thiếu một nửa số ảnh, một quy tắc kích thước bạn quên mất. Hãy để agent lập trình của bạn (Claude Code, Codex, Cursor) xây dựng một bài kiểm tra có thể lặp lại với Apidog CLI thay vì kiểm tra phản hồi thủ công.
![Workflow diagram: a developer prompt goes to a coding agent, which runs Apidog CLI to create an environment, endpoint and test case, calls the MiniMax image generations endpoint, and returns a test report showing status 200, a data[0].url present and no data[].error](https://assets.apidog.com/blog-next/2026/11/minimax-h3-image-api-body-2.png)
Thiết lập một lần:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install
Sau đó đưa cho agent của bạn một prompt:
In Apidog project <projectId>, create an environment "MiniMax Global" with base URL
https://api.minimax.io. Add the endpoint POST /v1/images/generations from the MiniMax
H3-Image API reference, with Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case that sends model MiniMax-H3-Image, area 1K, aspect_ratio 1:1, n 1,
and asserts HTTP 200, data[0].url exists, and no item in data has an error field.
Run it and summarize any failures.
Agent đọc schema của mỗi payload, xác thực JSON, tạo các tài nguyên và chạy test case:
apidog environment create "MiniMax Global" --project <projectId> --base-url https://api.minimax.io
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
--env-var "MINIMAX_API_KEY=$MINIMAX_API_KEY" -r cli,json
--env-var truyền khóa của bạn tại thời điểm chạy, nên nó không bao giờ nằm trong tệp đã lưu. Reporter cli in từng assertion dạng đậu hay rớt; json ghi một báo cáo mà agent của bạn đọc lại. Giữ test ở mức 1K: mỗi lần chạy là một lần tạo ảnh thật và bị tính phí. Cùng câu lệnh đó chạy trong CI với -r junit (xem hướng dẫn CI/CD với Apidog CLI và Apidog CLI trong Claude Code). Gói Free của Apidog hỗ trợ tới 4 người dùng.
Standard hay Highspeed: nên dùng model ID nào?
Cả hai ID nhận tham số giống hệt nhau, nên việc chuyển đổi chỉ là thay một chuỗi. Dùng MiniMax-H3-Image cho tài sản cuối cùng và các lô nhạy cảm về chi phí, còn MiniMax-H3-Image-Highspeed cho các bản xem trước tương tác, nơi độ trễ quan trọng hơn giá. Tài liệu API không đưa con số độ trễ, nên hãy tự đo trên prompt của riêng bạn. Đang cân nhắc các phương án khác? Đọc MiniMax H3-Image vs Nano Banana 2.1, hướng dẫn Nano Banana 2.1 API hoặc hướng dẫn GPT Image 2.6 API.
Câu hỏi thường gặp
Model ID của MiniMax H3-Image là gì? Dùng MiniMax-H3-Image cho model tiêu chuẩn hoặc MiniMax-H3-Image-Highspeed cho phiên bản nhanh hơn, đắt hơn. Cả hai hoạt động trên /v1/images/generations và /v1/images/edits với cùng tham số.
MiniMax H3-Image API có hoạt động với OpenAI SDK không? Có. Đặt base_url="https://api.minimax.io/v1" và gọi images.generate hoặc images.edit. Đặt max_retries=0, vì retry sẽ tạo ra các lần tạo ảnh mới bị tính phí.
Tôi có thể dùng bao nhiêu ảnh tham chiếu khi chỉnh sửa? Từ 1 đến 16 mỗi yêu cầu, mỗi ảnh từ 128 đến 8.192 pixel mỗi cạnh, với tổng phần thân yêu cầu dưới 64 MiB.
Một ảnh MiniMax H3-Image tốn bao nhiêu tiền? Theo ví dụ của MiniMax, một lệnh text-to-image tiêu chuẩn tốn khoảng $0.022 cho 1K và $0.069 cho 4K, với 4K giảm còn khoảng $0.034 cho đến ngày 17 tháng 11 năm 2026, 16:00 UTC.
Tại sao tôi nhận được mã 200 nhưng số ảnh ít hơn yêu cầu? Thành công một phần vẫn trả về 200. Các mục thất bại, bao gồm cả những mục bị chặn bởi kiểm tra an toàn, mang một đối tượng error thay vì url, và bạn không bị tính phí cho chúng.