> ## 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 dan Pengeditan Gambar FLUX Kontext

> Kirim tugas asinkron FLUX Kontext untuk pembuatan atau pengeditan gambar. API mengembalikan ID tugas; lakukan polling pada endpoint tugas untuk mendapatkan gambar yang dihasilkan.

```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": "flux-kontext-pro",
    "prompt": "Change hair color to blue",
    "image_urls": ["https://upload.gccai.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    "size": "16:9"
  }'
```

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

url = "https://gccai.heqingsong.uk/v1/images/generations"

payload = {
    "model": "flux-kontext-pro",
    "prompt": "Change hair color to blue",
    "image_urls": ["https://upload.gccai.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    "size": "16:9"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://gccai.heqingsong.uk/v1/images/generations";

const payload = {
  model: "flux-kontext-pro",
  prompt: "Change hair color to blue",
  image_urls: ["https://upload.gccai.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
  size: "16:9"
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

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

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Insufficient balance, please top up",
    "type": "payment_required"
  }
}
```

## Model yang Didukung

| Model | Deskripsi |
| - | - |
| `flux-kontext-pro` | Pembuatan dan pengeditan gambar berbasis konteks untuk alur kerja umum. |
| `flux-kontext-max` | Pembuatan dan pengeditan gambar berbasis konteks dengan kualitas lebih tinggi. |

Kedua model mendukung pembuatan gambar dari teks tanpa gambar referensi serta pengeditan gambar dengan gambar referensi.

## Otorisasi

**Authorization** `string` *required*

Semua endpoint memerlukan autentikasi Bearer Token.

Dapatkan API key dari [Manajemen API Key](https://gccai.heqingsong.uk/keys), lalu tambahkan ke header permintaan:

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required*

Nama model:

* `flux-kontext-pro`
* `flux-kontext-max`

**nsfw\_check** `boolean` (default: false)

Menentukan apakah moderasi konten dijalankan sebelum tugas gambar dikirim.

* `true`: periksa prompt dan gambar input dengan `omni-moderation-latest`
* `false` atau dihilangkan: tidak mengirim permintaan moderasi, tanpa biaya atau latensi moderasi tambahan (default)

**prompt** `string` *required*

Deskripsi teks untuk gambar yang akan dibuat atau perubahan yang akan diterapkan pada gambar referensi.

**image\_urls** `array`

Gambar referensi untuk pengeditan gambar. Berikan melalui URL yang dapat diakses publik atau dalam format Base64.

* Maksimum: 4 gambar
* Jumlah piksel gambar keluaran beserta semua gambar referensi tidak boleh melebihi 9 MP

Jika URL referensi tidak dapat diakses, tugas dapat menampilkan `temporarily unavailable dependency`. Periksa terlebih dahulu apakah URL bersifat publik, belum kedaluwarsa, dan tidak memblokir akses eksternal.

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

Rasio aspek gambar. Rasio aspek dan mode otomatis yang didukung:

* `1:1` (default)
* `4:3`
* `3:4`
* `16:9`
* `9:16`
* `3:2`
* `2:3`
* `21:9`
* `9:21`
* `auto` - Mengikuti rasio aspek gambar referensi

Jika `size` diatur ke `auto` dan `image_urls` diberikan, keluaran akan mengikuti rasio aspek gambar referensi. Jika tidak ada gambar referensi, rasio default `1:1` akan digunakan.

String piksel seperti `1024x1536` juga dapat diberikan. Kontext memetakannya ke rasio aspek terdekat yang didukung dan tidak menjamin dimensi piksel persis tersebut.

Parameter `resolution` tidak memengaruhi keluaran Kontext, yang tetap sekitar 1 MP. Jangan kirim `width` atau `height`; parameter tersebut tidak didukung oleh Kontext dan akan membuat tugas gagal.

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

Format gambar hasil: `png`, `jpeg`, atau `webp`. Default-nya adalah `png`.

**response\_format** `string`

Parameter kompatibilitas untuk bentuk respons. Nilai yang didukung: `url` dan `b64_json`. Parameter ini tidak mengubah format gambar; jika `output_format` juga diberikan, `output_format` diprioritaskan.

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

Jumlah gambar yang dibuat. Hanya nilai `1` yang didukung.

**seed** `integer`

Seed acak. Gunakan kembali seed dan parameter yang sama untuk menghasilkan gambar yang dapat direproduksi; hilangkan parameter ini untuk menggunakan seed acak.

**prompt\_upsampling** `boolean` (default: false)

Menentukan apakah prompt ditingkatkan dan ditulis ulang sebelum pembuatan gambar.

Tetapkan parameter ini secara eksplisit ke `false` untuk menonaktifkan penulisan ulang prompt.

**safety\_tolerance** `integer` (default: 2)

Toleransi keamanan dari `0` hingga `6`. Nilai yang lebih tinggi lebih permisif.

## Rasio Aspek yang Didukung

| Rasio aspek | Orientasi |
| - | - |
| `1:1` | Persegi (default) |
| `4:3` | Lanskap |
| `3:4` | Potret |
| `16:9` | Lanskap layar lebar |
| `9:16` | Potret vertikal |
| `3:2` | Lanskap klasik |
| `2:3` | Potret klasik |
| `21:9` | Lanskap ultra-lebar |
| `9:21` | Potret ultra-tinggi |

### Dimensi output aktual

| Rasio | Dimensi output aktual |
| - | - |
| `1:1` | 1024×1024 |
| `4:3` | 1184×880 |
| `3:4` | 880×1184 |
| `16:9` | 1392×752 |
| `9:16` | 752×1392 |
| `3:2` | 1248×832 |
| `2:3` | 832×1248 |
| `21:9` | 1568×672 |
| `9:21` | 672×1568 |

## Contoh Penggunaan

### Pembuatan gambar dari teks

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "A cozy reading nook with warm lamplight",
  "size": "4:3"
}
```

### Pengeditan gambar

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "Replace the background with a beach while preserving the person",
  "image_urls": ["https://example.com/portrait.jpg"],
  "size": "16:9",
  "output_format": "webp"
}
```

### Beberapa gambar referensi

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "Place the product from the first image into the room from the second image",
  "image_urls": [
    "https://example.com/product.jpg",
    "https://example.com/room.jpg"
  ],
  "size": "4:3"
}
```

## Respons

**code** `integer`

Kode status respons.

**data** `array`

Array hasil pengiriman tugas.

**Properti**

**status** `string`

Status pengiriman. Tugas yang berhasil diterima mengembalikan `submitted`.

**task\_id** `string`

Pengidentifikasi unik tugas. Gunakan untuk melakukan polling pada endpoint tugas.

## Mengambil Hasil

Lakukan polling pada `GET /v1/tasks/{task_id}` hingga tugas mencapai status `completed` atau `failed`. Lihat [API Status Tugas](https://gccai.heqingsong.uk/id/api-reference/tasks/status.md) untuk skema respons lengkap.

Tugas yang selesai mencakup satu gambar yang dihasilkan:

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://upload.gccai.ai/f/image/xxxxxxxx-flux-kontext.png"],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

URL gambar berada di `data.result.images[0].url[0]`. Masa berlakunya ditentukan oleh timestamp Unix di `data.result.images[0].expires_at`; unduh gambar sebelum waktu tersebut.

### Status tugas

| Status | Arti |
| - | - |
| `submitted` / `pending` | Tugas diterima atau berada dalam antrean; lanjutkan polling |
| `processing` | Gambar sedang dibuat; lanjutkan polling |
| `completed` | Tugas selesai; hasil tersedia di `result.images` |
| `failed` | Tugas gagal; alasannya tersedia di `data.error.message` dan dana dikembalikan sepenuhnya |

Contoh tugas yang gagal:

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

Parameter model yang tidak valid tidak menghasilkan error 400 secara sinkron. Pengiriman mengembalikan HTTP 200 dan `task_id`; saat dipolling, tugas berubah menjadi `failed`. Alasan spesifik selalu tersedia di `error.message`, sedangkan `error.code` adalah `task_failed`. Dana untuk tugas yang gagal dikembalikan sepenuhnya.

## Catatan

1. Tugas diproses secara asinkron. Respons pengiriman mengembalikan `task_id` untuk polling.
2. Parameter `n` harus bernilai `1`; setiap permintaan menghasilkan tepat satu gambar.
3. Gambar referensi dapat diberikan melalui URL yang dapat diakses publik atau dalam format Base64.
4. Hingga 4 gambar referensi didukung, dan jumlah piksel gambar keluaran beserta semua referensi tidak boleh melebihi 9 MP.
5. Tetapkan `prompt_upsampling: false` secara eksplisit untuk menonaktifkan penulisan ulang prompt.
6. Masa berlaku URL hasil ditentukan oleh nilai `expires_at` yang dikembalikan dalam respons tugas.


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