> ## 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 GPT-Image-2.5

>  - Pilih gpt-image-2.5-flare atau gpt-image-2.5-sunburst
- Pemrosesan asinkron mengembalikan task_id untuk mengambil hasil
- Mendukung teks-ke-gambar dan pengeditan dengan hingga 16 gambar referensi
- Mendukung 15 rasio, ukuran piksel presisi, serta resolusi 1K / 2K / 4K
- Tingkat kualitas low / medium / high / xhigh / max 

<Info>
  **Pemilihan model:** `gpt-image-2.5-flare` lebih cepat dan cocok untuk gambar berkualitas tinggi sehari-hari, pembuatan massal, dan prototipe. `gpt-image-2.5-sunburst` mengutamakan ketepatan pengeditan untuk gambar produk final, materi iklan, dan pengeditan detail bertahap. Harga kedua model sama.
</Info>

<RequestExample>
  ```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": "gpt-image-2.5-flare",
      "prompt": "sudut baca yang nyaman di dekat jendela saat hujan, cahaya lampu hangat",
      "size": "1:1",
      "resolution": "1k",
      "quality": "medium",
      "n": 1
    }'
  ```
</RequestExample>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

## Autentikasi

<ParamField header="Authorization" type="string" required>
  Semua endpoint menggunakan Bearer Token. Dapatkan kunci Anda di [halaman kunci API](https://apimart.ai/keys).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Pilih model

| Model                    | Kelebihan                      | Penggunaan yang disarankan                                              |
| ------------------------ | ------------------------------ | ----------------------------------------------------------------------- |
| `gpt-image-2.5-flare`    | Model default yang lebih cepat | Media sosial, produk, pencarian visual, prototipe, dan pembuatan massal |
| `gpt-image-2.5-sunburst` | Ketepatan pengeditan           | Gambar produk final, materi iklan, dan pengeditan detail bertahap       |

Dengan parameter yang sama, penggunaan token dan harga kedua model identik. Dibandingkan `gpt-image-2`, GPT-Image-2.5 menambahkan `xhigh` dan `max`; tingkat `medium` dan `high` menggunakan sekitar seperempat token keluaran dari tingkat bernama sama pada generasi sebelumnya.

## Parameter permintaan

<ParamField body="model" type="string" required>
  `gpt-image-2.5-flare` atau `gpt-image-2.5-sunburst`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Deskripsi gambar yang akan dibuat atau diedit. Jelaskan subjek, suasana, komposisi, gaya, pencahayaan, dan elemen yang perlu dipertahankan atau diubah.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Rasio aspek atau ukuran piksel yang presisi.

  * `auto`: dipilih otomatis berdasarkan prompt atau gambar referensi
  * Rasio: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`
  * Ukuran presisi, misalnya `1600x1200`

  <Tip>
    Untuk pengeditan gambar, abaikan `size` agar layanan menghitung ukuran dari rasio gambar input dan `resolution`.
  </Tip>
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  Tingkat resolusi: `1k`, `2k`, atau `4k`. Diabaikan saat `size` berisi ukuran piksel presisi.
</ParamField>

<ParamField body="quality" type="string" default="auto">
  Kualitas: `low`, `medium`, `high`, `xhigh`, `max`, atau `auto`.

  <Warning>
    `xhigh` dan `max` hanya tersedia untuk GPT-Image-2.5. Mengirimnya ke `gpt-image-2` menghasilkan HTTP 400 tanpa penurunan kualitas otomatis.
  </Warning>
</ParamField>

<ParamField body="n" type="integer" default="1">
  Jumlah gambar: `1` hingga `4`. Kirim sebagai angka, bukan string.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Format keluaran: `png`, `jpeg`, atau `webp`.
</ParamField>

<ParamField body="output_compression" type="integer">
  Kompresi dari `0` hingga `100`, hanya untuk `jpeg` dan `webp`.
</ParamField>

<ParamField body="background" type="string">
  Latar belakang: `transparent`, `opaque`, atau `auto`.

  <Warning>
    `transparent` membutuhkan `png` atau `webp`; JPEG tidak memiliki kanal alfa.
  </Warning>
</ParamField>

<ParamField body="moderation" type="string" default="low">
  Tingkat moderasi: `auto` atau `low`. Jika tidak dikirim, APIMart secara eksplisit mengirim `low`; nilai `auto` yang dikirim akan diteruskan.
</ParamField>

<ParamField body="image_urls" type="string[]">
  URL gambar referensi untuk pembuatan atau pengeditan, maksimal `16`. Mengirim bidang ini mengaktifkan mode pengeditan.

  Hanya URL HTTP(S) publik yang diterima. Unggah gambar lokal terlebih dahulu melalui `POST /v1/uploads/images`, lalu gunakan `url` yang dikembalikan.
</ParamField>

## Aturan ukuran

* Lebar dan tinggi harus merupakan kelipatan `16`
* Setiap sisi tidak boleh melebihi `3840` piksel
* Rasio sisi panjang terhadap sisi pendek maksimal `3:1`
* Jumlah piksel antara `655.360` dan `8.294.400`

<Warning>
  Resolusi di atas 2560×1440 bersifat eksperimental dan mungkin kurang stabil.
</Warning>

### Pemetaan rasio dan resolusi

| `size` | `1k`      | `2k`      | `4k`      |
| ------ | --------- | --------- | --------- |
| `1:1`  | 1024×1024 | 2048×2048 | 2880×2880 |
| `3:2`  | 1536×1024 | 2048×1360 | 3520×2336 |
| `2:3`  | 1024×1536 | 1360×2048 | 2336×3520 |
| `4:3`  | 1024×768  | 2048×1536 | 3312×2480 |
| `3:4`  | 768×1024  | 1536×2048 | 2480×3312 |
| `5:4`  | 1280×1024 | 2560×2048 | 3216×2576 |
| `4:5`  | 1024×1280 | 2048×2560 | 2576×3216 |
| `16:9` | 1536×864  | 2048×1152 | 3840×2160 |
| `9:16` | 864×1536  | 1152×2048 | 2160×3840 |
| `2:1`  | 2048×1024 | 2688×1344 | 3840×1920 |
| `1:2`  | 1024×2048 | 1344×2688 | 1920×3840 |
| `21:9` | 2016×864  | 2688×1152 | 3840×1648 |
| `9:21` | 864×2016  | 1152×2688 | 1648×3840 |
| `3:1`  | 1536×512  | 3072×1024 | 3840×1280 |
| `1:3`  | 512×1536  | 1024×3072 | 1280×3840 |

Ukuran presisi lain dapat digunakan jika memenuhi semua aturan.

## Contoh pengeditan

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "pertahankan produk dan teks kemasan, ubah latar menjadi studio putih lembut, lalu tambahkan bayangan alami",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

## Pengiriman dan kueri tugas

Setelah berhasil dikirim, ID tugas tersedia di `data[0].task_id`. Kueri [status tugas](/id/api-reference/tasks/status) setiap 2–5 detik hingga `completed` atau `failed`. Gunakan `POST /v1/tasks/batch` untuk beberapa tugas.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "result": {
      "images": [{
        "url": ["https://upload.apimart.ai/f/image/example.png"],
        "expires_at": 1789000000
      }]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}
```

URL gambar tersedia di `data.result.images[].url[]`. Unduh dan simpan file sesegera mungkin.

| Status       | Arti                                                      |
| ------------ | --------------------------------------------------------- |
| `submitted`  | Tugas dikirim                                             |
| `processing` | Pembuatan berlangsung                                     |
| `completed`  | Berhasil; `result.images` tersedia                        |
| `failed`     | Gagal; lihat `error.message`; dana reservasi dikembalikan |

## Penagihan

GPT-Image-2.5 ditagih berdasarkan pemakaian token aktual. Lihat [halaman harga](https://apimart.ai/pricing) atau `/api/pricing` untuk harga akun saat ini.

| Item                      | Harga per 1 juta token |
| ------------------------- | ---------------------- |
| Keluaran gambar           | \$30.00                |
| Masukan gambar            | \$8.00                 |
| Masukan gambar dari cache | \$2.00                 |
| Masukan teks              | \$5.00                 |
| Masukan teks dari cache   | \$1.25                 |

| `quality` pada 1024×1024 | Token keluaran | Biaya keluaran resmi |
| ------------------------ | -------------- | -------------------- |
| `low`                    | 196            | \$0.00588            |
| `medium`                 | 439            | \$0.01317            |
| `high`                   | 1756           | \$0.05268            |
| `xhigh`                  | 3122           | \$0.09366            |
| `max`                    | 7024           | \$0.21072            |

<Warning>
  Dengan `quality: "auto"`, layanan terlebih dahulu mereservasi biaya tingkat `max` untuk ukuran yang dipilih. Setelah selesai, biaya dihitung berdasarkan penggunaan aktual dan selisihnya dilepas.
</Warning>

Untuk `n > 1`, reservasi bertambah secara linear. Tugas yang gagal dikembalikan biayanya secara otomatis.

## Batas dan kesalahan umum

| Item                     | Batas atau solusi                                 |
| ------------------------ | ------------------------------------------------- |
| Gambar per permintaan    | 1–4                                               |
| Gambar referensi         | Maksimal 16                                       |
| Format keluaran          | PNG / JPEG / WebP                                 |
| Latar transparan         | Hanya PNG / WebP                                  |
| Streaming gambar parsial | Tidak didukung                                    |
| Kualitas tidak valid     | `xhigh` / `max` membutuhkan GPT-Image-2.5         |
| Ukuran tidak valid       | Gunakan kelipatan 16 dalam batas piksel dan rasio |

## Response

<ResponseField name="code" type="integer">
  Kode respons; 200 jika pengiriman berhasil.
</ResponseField>

<ResponseField name="data" type="array">
  Data respons pengiriman.

  <Expandable title="Item array">
    <ResponseField name="status" type="string">
      Status awal adalah `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID unik untuk mengkueri status dan hasil.
    </ResponseField>
  </Expandable>
</ResponseField>