MiniMax H3-Image API: Cara Membuat dan Mengedit Gambar

API MiniMax H3-Image menghasilkan dan mengedit gambar melalui dua endpoint REST: POST /v1/images/generations untuk text-to-image dan POST /v1/images/edits untuk mengedit dengan 1 hingga 16 gambar referensi. Anda mengirim kunci Bearer, ID model MiniMax-H3-Image (atau MiniMax-H3-Image-Highspeed), sebuah prompt, dan ukuran, lalu Anda menerima URL gambar atau data base64. API ini berjalan di platform pengembang MiniMax yang sama dengan MiniMax M3 API. Output mencapai sekitar 16 megapiksel tanpa upscaler.

Di bawah ini: kunci API, field-field yang penting, pengeditan, harga dengan diskon peluncuran, serta uji coba yang dijalankan agen dengan Apidog CLI. Baru mengenal model ini? Mulailah dengan apa itu MiniMax H3-Image.

Apa itu API MiniMax H3-Image?

API MiniMax H3-Image adalah endpoint yang dihosting oleh MiniMax untuk model open-weight H3-Image-nya, yang menangani text-to-image dan pengeditan gambar multi-referensi dalam satu checkpoint. Endpoint ini berada di https://api.minimax.io, menerima permintaan JSON, dan kompatibel dengan pemanggilan images.generate serta images.edit dari OpenAI SDK, sehingga sebagian besar kode gambar yang sudah ada hanya perlu base URL dan nama model baru.

Bobot modelnya juga bersifat publik: model card di Hugging Face mencantumkan diffusion transformer berparameter 33,1B di bawah lisensi MiniMax-H3-Image Community License. Self-hosting membutuhkan sekitar 69 GB untuk checkpoint ditambah text encoder sebesar 66,7 GB, sehingga API adalah jalur yang paling praktis bagi sebagian besar tim.

Detail sisi yang dihosting, dari referensi API MiniMax per 11-11-2026:

Dapatkan kunci API MiniMax Anda

1. Masuk ke platform pengembang MiniMax.
2. Buka Account Management, lalu API Keys, dan buat sebuah kunci.
3. Tambahkan saldo. Permintaan tanpa dana akan gagal dengan HTTP 402 dan kode error 1008 (saldo tidak mencukupi).
4. Ekspor kunci tersebut agar kode dan agen Anda membacanya dari environment, bukan dari file yang Anda commit:

export MINIMAX_API_KEY="your-key-here"

Setiap pemanggilan mengirimkannya sebagai Authorization: Bearer $MINIMAX_API_KEY.

Permintaan text-to-image pertama Anda

Pemanggilan paling sederhana yang berguna membutuhkan model, prompt, dan ukuran atau tingkatan area:

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"
  }'

Dengan OpenAI Python SDK, arahkan base_url ke MiniMax dan matikan 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

Baris max_retries=0 itu penting. Endpoint ini tidak idempoten: server menyelesaikan dan menagih pekerjaan meskipun klien Anda kehabisan waktu, sehingga retry otomatis akan menagih dua kali. Sebagai gantinya, tetapkan timeout 600 detik.

Parameter permintaan yang penting

Anda mengatur ukuran output dengan salah satu dari dua cara, dan keduanya tidak bisa dicampur.

Piksel eksak. Atur size ke WIDTHxHEIGHT, misalnya 4096x4096. Total area harus antara 655.360 dan 20.000.000 piksel, dan rasio aspek antara 1:3 hingga 3:1. Jangan mengirim aspect_ratio atau area dalam mode ini, bahkan sebagai auto, atau Anda akan mendapat error 400.

Tingkatan plus rasio. Biarkan size sebagai auto dan atur area (1K, 2K, atau 4K, default 4K) dan aspect_ratio (sembarang X:Y dari 1:3 hingga 3:1). Server akan menghitung pikselnya; 2K pada 16:9 menghasilkan 2720 x 1536.

Field lainnya:

Ada dua aturan yang sering menjebak. Pertama, jika Anda mematikan peningkatan prompt, Anda harus memberikan size yang eksak atau aspect_ratio eksplisit; auto akan mengembalikan 400. Kedua, b64_json membatasi total area output: 20.000.000 piksel untuk PNG (satu gambar dengan ukuran apa pun) dan 80.000.000 untuk JPEG atau WebP (empat gambar 4K atau sepuluh gambar 2K). Untuk batch yang lebih besar, gunakan URL.

Model card menyatakan H3-Image bekerja paling baik di sekitar 16 MP: 4096x4096 (1:1), 5472x3072 (16:9), atau 6272x2688 (21:9).

Edit gambar dengan hingga 16 referensi

Pengeditan menggunakan field yang sama ditambah array images. Rujuk input berdasarkan posisinya di 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 ini juga menerima multipart/form-data, yang digunakan oleh images.edit dari OpenAI SDK saat Anda mengunggah file. Batasannya, dari referensi edits:

• 1 hingga 16 gambar dalam format JPG, PNG, WebP, HEIC, atau HEIF
• Tiap sisi antara 128 dan 8.192 piksel, rasio sisi panjang-ke-pendek maksimal 4:1
• Total body permintaan hingga 64 MiB; base64 menambah sekitar sepertiga ukuran, jadi gunakan URL publik untuk input besar

Membaca respons dan menangani error

Pemanggilan yang berhasil mengembalikan satu item data untuk setiap gambar yang diminta, sesuai urutan:

{
  "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..."
}

Tiga kebiasaan menjaga integrasi Anda tetap andal:

1. Periksa setiap item untuk error. Status HTTP adalah 200 jika setidaknya satu gambar berhasil, jadi kode 200 tidak berarti semua n gambar kembali. Jika semua gambar gagal, Anda akan mendapat 402, 422, atau 500.
2. Segera unduh URL-nya. MiniMax menyatakan URL tidak dijamin tetap tersedia, jadi salin filenya ke penyimpanan Anda sendiri.
3. Catat request_id. Ini adalah trace ID yang diminta tim dukungan.

Pelanggaran rate limit mengembalikan 429. Kode 1002 berarti Anda melewati batas gambar per menit, dan setiap permintaan dihitung sebagai n gambar, sehingga batch berisi 10 memakai 10 dari kuota Anda sekaligus.

Harga MiniMax H3-Image dan diskon peluncuran

Penagihan dilakukan per token, dan Anda hanya membayar gambar yang berhasil. Dari halaman harga MiniMax, dibaca pada 11-11-2026:

MiniMax juga menerbitkan contoh biaya per gambar untuk model standar:

Highspeed berbiaya sekitar 1,6 hingga 2 kali lipat per gambar ($0.13001 untuk 4K, $0.06501 dengan diskon). Panjang prompt memengaruhi sisi input, jadi anggap angka-angka ini sebagai perkiraan.

Penawaran peluncuran: hingga 17 November 2026 pukul 16:00 UTC, MiniMax memberikan diskon 50% pada total biaya permintaan untuk kedua model jika gambar yang dihasilkan memiliki setidaknya 16.600.000 piksel. Gambar 4096x4096 (16.777.216 piksel) memenuhi syarat; gambar 2K tidak. Mencari alternatif gratis? Lihat cara menggunakan MiniMax H3-Image secara gratis.

Biarkan agen coding Anda mengujinya dengan Apidog CLI

API gambar sering gagal secara senyap: respons 200 dengan setengah gambar hilang, atau aturan ukuran yang Anda lupakan. Biarkan agen coding Anda (Claude Code, Codex, Cursor) membangun pengujian yang dapat diulang dengan Apidog CLI alih-alih memeriksa respons secara manual.

Pengaturan awal sekali saja:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

Lalu berikan satu prompt ke agen Anda:

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.

Agen membaca skema setiap payload, memvalidasi JSON-nya, membuat resource-nya, dan menjalankan 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 meneruskan kunci Anda saat runtime, sehingga tidak pernah tersimpan dalam file. Reporter cli mencetak setiap assertion sebagai lulus atau gagal; json menulis laporan yang dapat dibaca kembali oleh agen Anda. Pertahankan pengujian pada 1K: setiap eksekusi adalah generasi sungguhan yang ditagih. Baris yang sama dapat dijalankan di CI dengan -r junit (lihat panduan CI/CD Apidog CLI dan Apidog CLI di Claude Code). Paket Free Apidog mencakup hingga 4 pengguna.

Standar atau Highspeed: ID model mana yang dipilih?

Kedua ID menerima parameter yang identik, sehingga berpindah hanya mengganti satu string. Gunakan MiniMax-H3-Image untuk aset final dan batch yang sensitif terhadap biaya, serta MiniMax-H3-Image-Highspeed untuk pratinjau interaktif di mana latensi lebih penting daripada harga. Referensi API tidak memberikan angka latensi, jadi ukur sendiri dengan prompt Anda. Sedang mengevaluasi alternatif? Baca MiniMax H3-Image vs Nano Banana 2.1, panduan Nano Banana 2.1 API, atau panduan GPT Image 2.6 API.

FAQ

Apa ID model MiniMax H3-Image? Gunakan MiniMax-H3-Image untuk model standar atau MiniMax-H3-Image-Highspeed untuk versi yang lebih cepat dan lebih mahal. Keduanya bekerja di /v1/images/generations dan /v1/images/edits dengan parameter yang sama.

Apakah API MiniMax H3-Image kompatibel dengan OpenAI SDK? Ya. Atur base_url="https://api.minimax.io/v1" dan panggil images.generate atau images.edit. Atur max_retries=0, karena retry akan membuat generasi baru yang ditagih.

Berapa banyak gambar referensi yang bisa saya gunakan untuk mengedit? 1 hingga 16 per permintaan, masing-masing 128 hingga 8.192 piksel per sisi, dengan total body permintaan di bawah 64 MiB.

Berapa biaya satu gambar MiniMax H3-Image? Contoh dari MiniMax menempatkan pemanggilan text-to-image standar sekitar $0.022 untuk 1K dan $0.069 untuk 4K, dengan 4K dipotong menjadi sekitar $0.034 hingga 17 November 2026, 16:00 UTC.

Mengapa saya mendapat kode 200 tetapi jumlah gambar lebih sedikit dari yang diminta? Keberhasilan parsial tetap mengembalikan 200. Item yang gagal, termasuk yang diblokir oleh pemeriksaan keamanan, membawa objek error alih-alih url, dan Anda tidak ditagih untuk itu.