> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pembuatan Gambar MiniMax-H3-Image

>  - Menggunakan model standar minimax-h3-image, unggul untuk fotografi realistis, poster, foto produk, dan gambar berisi teks
- Pemrosesan asinkron mengembalikan task_id untuk mengambil hasil
- Mendukung teks-ke-gambar dan pengeditan dengan hingga 16 gambar referensi
- Hingga 10 gambar per permintaan, dengan peningkatan prompt bawaan (dapat dinonaktifkan)
- Mendukung tingkat 1K / 2K / 4K + rasio aspek, atau ukuran piksel langsung (maksimal 20 megapiksel) 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "Kafe tepi pantai saat senja, gaya fotografi realistis, nuansa warna hangat",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "minimax-h3-image",
        "prompt": "Kafe tepi pantai saat senja, gaya fotografi realistis, nuansa warna hangat",
        "size": "16:9",
        "resolution": "2K",
        "n": 1,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "minimax-h3-image",
      prompt: "Kafe tepi pantai saat senja, gaya fotografi realistis, nuansa warna hangat",
      size: "16:9",
      resolution: "2K",
      n: 1,
    }),
  },
);

console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Parameter permintaan tidak valid",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Autentikasi gagal. Periksa kunci API Anda.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Saldo akun tidak mencukupi",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Permintaan terlalu sering, silakan coba lagi nanti",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "Kesalahan internal server, silakan coba lagi nanti",
    "type": "server_error"
  }
}
```

## Autentikasi

**Authorization** `string` *required*

Semua endpoint menggunakan Bearer Token. Dapatkan kunci Anda di [halaman kunci API](https://apimart.ai/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Tentang model

| Model | Karakteristik | Skenario penggunaan |
| - | - | - |
| `minimax-h3-image` | Versi standar, harga satuan lebih rendah | Pembuatan gambar massal, fotografi realistis, poster, foto produk, gambar berisi teks |
| `minimax-h3-image-highspeed` | Versi cepat, gambar dihasilkan lebih cepat; harga input / output gambar 2 kali versi standar | Skenario yang sensitif terhadap kecepatan respons; lihat [MiniMax-H3-Image-Highspeed](https://docs.apimart.ai/id/api-reference/images/minimax-h3-image-highspeed/generation.md) |

Secara default, MiniMax H3 Image terlebih dahulu memperluas prompt menjadi deskripsi gambar yang detail sebelum membuat gambar. Hasil perluasan dapat dilihat di `revised_prompt` pada hasil kueri. Untuk membuat gambar persis sesuai teks asli, lihat [Menonaktifkan peningkatan prompt](#menonaktifkan-peningkatan-prompt).

> [!WARNING]
>
> Jika `resolution` tidak dikirim, keluaran default adalah **4K** (sekitar 16 megapiksel), dengan harga satuan sekitar 3 kali 1K / 2K. Jika tidak memerlukan 4K, kirim `"resolution": "2K"` secara eksplisit.

## Parameter permintaan

**model** `string` *required*

Nama model pembuatan gambar, tetap `minimax-h3-image`.

**prompt** `string` *required*

Deskripsi teks untuk pembuatan atau pengeditan gambar.

Mendukung bahasa Tionghoa dan Inggris. Setelah spasi di awal dan akhir dihapus, panjangnya `1` hingga `32,000` karakter.

**image\_urls** `string[]`

Array gambar referensi, maksimal `16`. Jika dikirim, mode pengeditan aktif secara otomatis.

Setiap item dapat berupa tautan langsung `http(s)://` yang dapat diakses publik, atau Base64 inline dalam format `data:image/png;base64,...` (platform mengubahnya menjadi tautan terlebih dahulu sebelum diteruskan ke model).

Lihat [Persyaratan gambar referensi](#persyaratan-gambar-referensi).

**size** `string` (default: auto)

Rasio aspek atau ukuran piksel presisi untuk gambar keluaran.

Nilai yang didukung:

* `auto`: model menentukan komposisi dan rasio berdasarkan prompt
* Rasio aspek: format `X:Y`, X dan Y bilangan bulat `1` hingga `300`, rasio antara `1:3` dan `3:1` (inklusif), misalnya `1:1`, `4:3`, `16:9`, `9:16`, `3:1`
* Piksel presisi: `lebarxtinggi`, misalnya `2048x1152` (pemisah `X`, `×`, `*` juga didukung)

Lihat [Aturan ukuran](#aturan-ukuran).

**resolution** `string` (default: 4K)

Tingkat resolusi; bersama rasio aspek menentukan piksel keluaran sebenarnya.

* `1K`: sekitar 1 megapiksel
* `2K`: sekitar 4,2 megapiksel
* `4K` (default): sekitar 16 megapiksel

Huruf kecil juga didukung.

> [!WARNING]
>
> Saat `size` menggunakan format piksel presisi, `resolution` **tidak boleh** dikirim; jika dikirim, akan mengembalikan 400.

**n** `integer` (default: 1)

Jumlah gambar yang dibuat, dari `1` hingga `10`.

**prompt\_optimizer** `boolean` (default: true)

Apakah prompt diperluas secara otomatis.

Nilai `false` hanya berlaku untuk teks-ke-gambar dan ukuran harus ditentukan secara eksplisit; lihat [Menonaktifkan peningkatan prompt](#menonaktifkan-peningkatan-prompt).

**output\_format** `string` (default: jpeg)

Format file keluaran.

* `jpeg` (default, dapat juga ditulis `jpg`)
* `png`
* `webp`

**output\_compression** `integer` (default: 95)

Kualitas kompresi, dari `0` hingga `100`. Tidak berlaku untuk `png`.

**watermark** `boolean` (default: false)

Apakah menambahkan watermark AI yang terlihat pada gambar. Tidak memengaruhi penanda implisit dalam metadata gambar.

> [!NOTE]
>
> Parameter berikut tidak didukung dan akan diabaikan jika dikirim: `quality`, `style`, `seed`, `negative_prompt`, `background`, `mask_url`.
>
> Hasil selalu dikembalikan sebagai URL; mengirim `response_format: "b64_json"` akan mengembalikan 400.

## Aturan ukuran

| Yang Anda inginkan | Cara mengirim |
| - | - |
| Default (4K, rasio dipilih model) | Jangan kirim parameter ukuran |
| Tingkat + rasio aspek | `size: "16:9"`, `resolution: "2K"` |
| Hanya mengatur tingkat, rasio ditentukan model | `resolution: "1K"` (`size` tidak dikirim atau `auto`) |
| Kontrol presisi hingga piksel | `size: "2048x1152"` (**jangan kirim `resolution`**) |

### Tingkat + rasio aspek

Tingkat menentukan luas total, rasio aspek menentukan bentuk:

| Tingkat | Luas target | Contoh keluaran hasil uji |
| - | - | - |
| `1K` | sekitar 1024×1024 (sekitar 1 megapiksel) | Rasio otomatis → 1184×880 |
| `2K` | sekitar 2048×2048 (sekitar 4,2 megapiksel) | `1:1` → 2048×2048 |
| `4K` (default) | sekitar 4096×4096 (sekitar 16 megapiksel) | Rasio otomatis → 3552×4736 |

Piksel keluaran sebenarnya dibulatkan oleh model berdasarkan rasio dan tingkat; nilai yang dikembalikan yang berlaku. Untuk ukuran presisi, gunakan format piksel.

### Piksel presisi

Saat menggunakan `size: "lebarxtinggi"`, ketentuan berikut harus dipenuhi:

| Batasan | Nilai |
| - | - |
| Total piksel (lebar × tinggi) | `655,360` \~ `20,000,000` |
| Rasio aspek | `1:3` \~ `3:1` |
| Dengan `resolution` | Tidak boleh dikirim bersamaan |

* ✅ `1024x1024`, `2048x1152`, `1536x1536`, `4000x5000`
* ❌ `512x512` (luas terlalu kecil), `4000x1000` (rasio melebihi 3:1), `5000x5000` (melebihi 20 megapiksel)

## Persyaratan gambar referensi

| Item | Persyaratan |
| - | - |
| Jumlah | Maksimal 16 |
| Format | JPG / JPEG / PNG / WebP / HEIC / HEIF (GIF tidak didukung) |
| Ukuran per gambar | Tidak lebih dari 64 MB |
| Dimensi per gambar | Setiap sisi 128 \~ 8192 piksel, sisi panjang ÷ sisi pendek ≤ 4 |

> [!WARNING]
>
> Saat menggunakan URL, pastikan tautan **dapat diakses publik**. Jika tautan tidak dapat diakses, tugas akan gagal pada tahap pembuatan (`status` bernilai `failed`, biaya dikembalikan penuh).
>
> Dalam mode pengeditan, peningkatan prompt selalu aktif dan tidak dapat dinonaktifkan.

## Menonaktifkan peningkatan prompt

Secara default, model memperluas prompt terlebih dahulu sebelum membuat gambar. Untuk membuat gambar persis sesuai teks asli, kirim `"prompt_optimizer": false`, dengan syarat:

* Hanya untuk **teks-ke-gambar**; jika ada `image_urls`, akan mengembalikan 400
* **Ukuran harus ditentukan secara eksplisit**: `size` harus berupa rasio aspek (misalnya `1:1`) atau piksel (misalnya `1024x1024`), bukan `auto` atau tidak dikirim

Setelah dinonaktifkan, model hanya membaca sekitar 4096 token pertama dari prompt.

## Response

**code** `integer`

Kode respons; 200 jika pengiriman berhasil.

**data** `array`

Data respons pengiriman.

**Item array**

**status** `string`

Status awal adalah `submitted`.

**task\_id** `string`

Pengenal unik tugas, digunakan untuk mengkueri status dan hasil pembuatan.

## Respons pengiriman

Setelah pengiriman berhasil, ID tugas asinkron langsung dikembalikan:

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## Mengkueri hasil tugas

Gunakan `task_id` dari respons pengiriman untuk memanggil [API kueri tugas](https://docs.apimart.ai/id/api-reference/tasks/status.md):

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

Hasil uji: satu gambar 1K / 2K sekitar 10 \~ 20 detik, 4K sekitar 20 detik, dan pengeditan dengan gambar referensi sekitar 20 detik. Disarankan melakukan polling setiap 3 \~ 5 detik hingga status menjadi `completed` atau `failed`. Satu tugas dapat berjalan hingga 600 detik; atur timeout polling klien ke 10 menit.

### Tugas berhasil

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "created": 1794450409,
    "completed": 1794450428,
    "actual_time": 19,
    "estimated_time": 60,
    "cost": 0.0493,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example_0.jpeg",
            "https://upload.apimart.ai/f/image/example_1.jpeg"
          ],
          "expires_at": 1794536828,
          "revised_prompt": "The image is a realistic, close-up still life photograph of ...",
          "revised_prompts": [
            "The image is a realistic ...",
            "The image is a professional ..."
          ]
        }
      ]
    }
  }
}
```

URL gambar ada di `data.result.images[0].url[]`, dan seluruh `n` gambar berada dalam satu array ini. Unduh dan simpan sebelum `expires_at`. Jika tugas gagal, `status` bernilai `failed`, alasannya ada di `error.message`, dan biaya dikembalikan penuh secara otomatis.

## Contoh penggunaan

### Teks-ke-gambar (default 4K)

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "A cozy coffee shop by the sea at sunset, photorealistic, warm tones"
}
```

### Teks-ke-gambar (1K + rasio aspek, 4 gambar sekaligus)

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "Foto produk headphone bergaya minimalis, latar belakang putih, bayangan lembut",
  "size": "1:1",
  "resolution": "1K",
  "n": 4
}
```

### Piksel presisi + PNG

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "Poster pemandangan kota di malam hari, lampu neon, gaya cyberpunk, teks judul NIGHT CITY",
  "size": "2048x1152",
  "output_format": "png"
}
```

### Pengeditan dengan gambar referensi

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "Kenakan jaket dari gambar kedua pada orang di gambar pertama, latar belakang tetap sama",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/jacket.png"
  ],
  "resolution": "2K"
}
```

### Menonaktifkan peningkatan prompt

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "a red apple on a wooden table, top view",
  "size": "1:1",
  "resolution": "1K",
  "prompt_optimizer": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.