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

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

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "Change hair color to blue",
      "image_urls": ["https://upload.apimart.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://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-kontext-pro",
    prompt: "Change hair color to blue",
    image_urls: ["https://upload.apimart.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));
  ```
</RequestExample>

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

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

<ParamField header="Authorization" type="string" required>
  Semua endpoint memerlukan autentikasi Bearer Token.

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

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Nama model:

  * `flux-kontext-pro`
  * `flux-kontext-max`
</ParamField>

<ParamField body="prompt" type="string" required>
  Deskripsi teks untuk gambar yang akan dibuat atau perubahan yang akan diterapkan pada gambar referensi.
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Rasio aspek gambar. Nilai yang didukung:

  * `1:1` (default)
  * `4:3`
  * `3:4`
  * `16:9`
  * `9:16`
  * `3:2`
  * `2:3`
  * `21:9`
  * `9:21`

  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.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Format gambar hasil: `png`, `jpeg`, atau `webp`. Default-nya adalah `png`.
</ParamField>

<ParamField body="response_format" type="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.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Jumlah gambar yang dibuat. Hanya nilai `1` yang didukung.
</ParamField>

<ParamField body="seed" type="integer">
  Seed acak. Gunakan kembali seed dan parameter yang sama untuk menghasilkan gambar yang dapat direproduksi; hilangkan parameter ini untuk menggunakan seed acak.
</ParamField>

<ParamField body="prompt_upsampling" type="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.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Toleransi keamanan dari `0` hingga `6`. Nilai yang lebih tinggi lebih permisif.
</ParamField>

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

<ResponseField name="code" type="integer">
  Kode status respons.
</ResponseField>

<ResponseField name="data" type="array">
  Array hasil pengiriman tugas.

  <Expandable title="Properti">
    <ResponseField name="status" type="string">
      Status pengiriman. Tugas yang berhasil diterima mengembalikan `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Pengidentifikasi unik tugas. Gunakan untuk melakukan polling pada endpoint tugas.
    </ResponseField>
  </Expandable>
</ResponseField>

## Mengambil Hasil

Lakukan polling pada `GET /v1/tasks/{task_id}` hingga tugas mencapai status `completed` atau `failed`. Lihat [API Status Tugas](/id/api-reference/tasks/status) 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.apimart.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.