> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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 inpainting lokal dengan mask PNG transparan
- Mendukung 15 rasio, ukuran piksel presisi, serta resolusi 1K / 2K / 4K
- Tingkat kualitas low / medium / high / xhigh / max 

> [!NOTE]
>
> **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.

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/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
  }'
```

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

## Autentikasi

**Authorization** `string` *required*

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

```
Authorization: Bearer YOUR_API_KEY
```

## 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

**model** `string` *required*

`gpt-image-2.5-flare` atau `gpt-image-2.5-sunburst`.

**prompt** `string` *required*

Deskripsi gambar yang akan dibuat atau diedit. Jelaskan subjek, suasana, komposisi, gaya, pencahayaan, dan elemen yang perlu dipertahankan atau diubah.

**size** `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`.

**resolution** `string` (default: 1k)

Tingkat resolusi: `1k`, `2k`, atau `4k`. Diabaikan saat `size` berisi ukuran piksel presisi.

**quality** `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.

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

Jumlah gambar: `1` hingga `4`. Kirim sebagai angka, bukan string.

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

Format keluaran: `png`, `jpeg`, atau `webp`.

**output\_compression** `integer`

Kompresi dari `0` hingga `100`, hanya untuk `jpeg` dan `webp`.

**background** `string`

Latar belakang: `transparent`, `opaque`, atau `auto`.

> [!WARNING]
>
> `transparent` membutuhkan `png` atau `webp`; JPEG tidak memiliki kanal alfa.

**moderation** `string` (default: low)

Tingkat moderasi: `auto` atau `low`. Jika tidak dikirim, GccAi secara eksplisit mengirim `low`; nilai `auto` yang dikirim akan diteruskan.

**image\_urls** `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.

**mask\_url** `string`

Gambar mask untuk inpainting lokal. Parameter ini hanya berlaku jika `image_urls` juga dikirim. `gpt-image-2.5-flare` dan `gpt-image-2.5-sunburst` sama-sama mendukung parameter ini.

Kirim satu string dalam salah satu format berikut:

* URL gambar HTTP(S) yang dapat diunduh langsung oleh server
* Data URL PNG dalam format `data:image/png;base64,...`

Persyaratan mask:

* Gunakan PNG dengan kanal alfa transparan; PNG juga disarankan untuk gambar sumber
* Dimensi piksel harus sama persis dengan `image_urls[0]`. Sesuaikan dengan gambar input pertama, bukan `size` output
* Piksel yang sepenuhnya transparan (`alpha=0`) menandai area yang akan diedit; area lainnya digunakan untuk dipertahankan
* Kirim satu mask per permintaan. Jika ada beberapa gambar referensi, mask hanya berlaku pada gambar input pertama
* Panduan ukuran file umum menyebut kurang dari `50 MB`, sedangkan penjelasan parameter `mask` menyebut kurang dari `4 MB`. Sebelum diverifikasi, gunakan batas `4 MB` yang lebih ketat

> [!WARNING]
>
> Gambar hitam-putih biasa tanpa kanal alfa tidak dapat langsung digunakan sebagai mask. GccAi tidak menambahkan kanal alfa dan saat ini tidak memvalidasi lebih dahulu apakah dimensi mask sama dengan gambar sumber; pemanggil harus memastikan keduanya.

> [!NOTE]
>
> URL HTTP(S) harus dapat diakses tanpa Cookie atau header autentikasi tambahan. URL bertanda tangan harus tetap berlaku selama antrean dan eksekusi. Batas unduhan default adalah `20 MB` dengan timeout `60` detik; konfigurasi deployment dapat mengganti nilai default ini.
>
> Mask memandu pengeditan, tetapi model tidak menjamin bahwa piksel di luar batas mask akan tetap sepenuhnya sama.

## 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.

### 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"
}
```

### Inpainting lokal dengan mask

Contoh ini hanya mengedit area mask yang sepenuhnya transparan. Dimensi mask harus sama dengan `product.png`.

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "ganti hanya area yang ditutupi mask transparan dengan pita emas, pertahankan produk dan bagian latar lainnya",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}
```

## Pengiriman dan kueri tugas

Setelah berhasil dikirim, ID tugas tersedia di `data[0].task_id`. Kueri [status tugas](https://gccai.heqingsong.uk/id/api-reference/tasks/status.md) 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.gccai.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://gccai.heqingsong.uk/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.

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

**code** `integer`

Kode respons; 200 jika pengiriman berhasil.

**data** `array`

Data respons pengiriman.

**Item array**

**status** `string`

Status awal adalah `submitted`.

**task\_id** `string`

ID unik untuk mengkueri status dan hasil.


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