> ## 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 Panjang Kling V4 Long Image

> Buat gambar detail produk atau desain halaman web dalam 1K / 2K. Mendukung short / medium / long untuk ecommerce serta referensi produk, gaya, dan subjek. Satu PNG per permintaan.

```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": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
}'
```

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

payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": True
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

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

```json 400 theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "reference image is not accessible for kling-v4-long-image: image_urls[0] returned HTTP 404; make sure the URL is public and still valid",
    "param": "",
    "type": "invalid_request_error"
  }
}
```

Kirim permintaan asinkron ke `POST /v1/images/generations` dengan `model: "kling-v4-long-image"`. Ambil `data[0].task_id`, lalu periksa `GET /v1/tasks/{task_id}`. Setiap permintaan menghasilkan satu PNG panjang; mode web menghasilkan gambar desain halaman.

## Pilih mode

| Mode | `skill` | Referensi | Panjang |
| - | - | - | - |
| Halaman detail produk | `ecommerce` | `image_urls`: wajib 1–3 gambar produk | `short` / `medium` / `long` |
| Desain halaman web | `webpage` | `image_with_roles`: gaya dan subjek opsional, masing-masing maksimal satu gambar | Hilangkan `length` |

## Autentikasi

**Authorization** `string` *required*

Gunakan `Authorization: Bearer <token>`, dengan `<token>` sebagai API key APIMart Anda.

## Parameter permintaan

**model** `string` *required*

Harus `kling-v4-long-image`.

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

Wajib dan tidak boleh hanya spasi. Maksimal 166.000 karakter untuk bahasa Inggris saja dan 71.000 untuk Mandarin atau bahasa serupa; teks campuran dihitung proporsional. Jelaskan tata letak, bagian konten, teks, gaya, dan subjek.

**skill** `string` *required*

Wajib: `ecommerce` untuk detail produk atau `webpage` untuk desain halaman web, tanpa membedakan huruf besar/kecil. Setiap mode memakai kolom referensi berbeda.

**length** `string` (default: medium)

Hanya untuk `skill: "ecommerce"`: `short`, `medium` (default), atau `long`, kira-kira 2–5, 6–10, atau 11–18 bagian konten. Konten dan tinggi aktual bergantung pada hasil. Hilangkan kolom ini pada mode web; mengirimnya menghasilkan HTTP 400.

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

Mendukung `1K` (default) dan `2K`, tanpa membedakan huruf besar/kecil, untuk semua panjang ecommerce termasuk `long + 2K`. Lebar keluaran masing-masing 1024 dan 2048 px; tingginya bergantung pada konten. `4K` tidak didukung.

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

Hanya untuk ecommerce: wajib 1–3 gambar produk. Pada mode web, hilangkan kolom ini dan gunakan `image_with_roles`. Berikan URL gambar langsung yang publik. File lokal dapat diunggah melalui [API unggah gambar](https://docs.apimart.ai/id/api-reference/uploads/images.md), lalu gunakan `url` yang dikembalikan.

**image\_with\_roles** `object[]`

Opsional, hanya untuk web. Maksimal satu gambar `style` dan satu `subject`; salah satu atau keduanya boleh dihilangkan. Hilangkan kolom ini pada mode ecommerce.

**Item array**

**url** `string` *required*

URL langsung gambar referensi yang dapat diakses publik.

**role** `string` *required*

`style` memandu gaya visual dan tata letak; `subject` menentukan subjek yang dipertahankan. Setiap peran hanya boleh muncul sekali.

**n** `integer`

Setiap permintaan menghasilkan satu gambar panjang. Hilangkan kolom ini atau gunakan bilangan bulat `1`; nilai lain menghasilkan HTTP 400.

**watermark** `boolean`

Hilangkan kolom ini atau gunakan `false`; `true` menghasilkan HTTP 400.

> [!WARNING]
>
> Jangan kirim `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation`, atau `sequential_image_generation_options`. Nilai `null` atau string kosong pada kolom tersebut juga menghasilkan HTTP 400.

## Persyaratan dan penanda referensi

Mendukung JPG / JPEG / PNG. Maksimal 30 MB per gambar, kedua sisi minimal 300 px, rasio 2:5–5:2. URL dengan HTTP 403 / 404 / 410, dimensi atau rasio tidak valid, atau file terlalu besar mengembalikan HTTP 400 sinkron, tanpa tugas atau biaya pembuatan. Kegagalan lain seperti waktu tunggu server asal habis diterima terlebih dahulu; tugas kemudian gagal dan biaya di muka dikembalikan.

Gunakan `@Image1`, `@Image2`, dan seterusnya dalam prompt. Ecommerce mengikuti urutan `image_urls`; web mengikuti gaya lalu subjek. Jika hanya satu gambar diberikan, gambar itu adalah `@Image1`.

## Contoh permintaan

Kirim ke `POST /v1/images/generations`. Ganti URL contoh dengan tautan langsung yang dapat diakses.

### Halaman produk panjang dalam 2K

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a long product detail page using the front view in @Image1, side view in @Image2, and close-up in @Image3. Include key features, materials, use scenes, and care instructions.",
  "image_urls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-detail.png"
  ],
  "length": "long",
  "resolution": "2K"
}'
```

### Web dengan referensi gaya dan subjek

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "webpage",
  "prompt": "Design a product landing page using the visual style of @Image1 and preserving the product in @Image2. Include a hero section, features, and a call to action.",
  "image_with_roles": [
    {
      "url": "https://example.com/style.png",
      "role": "style"
    },
    {
      "url": "https://example.com/product.jpg",
      "role": "subject"
    }
  ],
  "resolution": "2K"
}'
```

### Web hanya dari prompt

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "webpage",
  "prompt": "Design a welcoming coffee shop webpage with warm colors, a hero section, a menu, and store information",
  "resolution": "1K"
}'
```

## Periksa tugas

Periksa [API kueri tugas](https://docs.apimart.ai/id/api-reference/tasks/status.md) sekitar setiap 10 detik. Simpan `task_id` dan hindari permintaan pembuatan duplikat meskipun menunggu lama.

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

| Status (`data.status`) | Tindakan |
| - | - |
| `pending` / `processing` | Lanjutkan pemeriksaan. `data.cost` adalah biaya di muka dan `data.billing_status` adalah `held`. |
| `completed` | Baca `data.result.images[0].url[0]`. `data.billing_status` adalah `settled` dan `data.cost` merupakan biaya akhir. |
| `failed` | Baca `data.error.message`. `data.billing_status` adalah `refunded`, `data.cost` adalah `0`, dan biaya di muka dikembalikan sepenuhnya. |

Berikut adalah struktur hasil yang berhasil. `images` dan `url` berupa array; model ini menghasilkan satu gambar panjang per permintaan.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_long_image",
    "status": "completed",
    "progress": 100,
    "billing_status": "settled",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-long-image.png"
          ],
          "expires_at": 1795331293
        }
      ]
    }
  }
}
```

Unduh sebelum timestamp Unix dalam detik pada `data.result.images[0].expires_at`. Tautan akan kedaluwarsa setelahnya.

> [!NOTE]
>
> Pembuatan biasanya memerlukan beberapa menit; satu sampel `long + 2K` memerlukan 432 detik. `estimated_time` saat ini selalu bernilai 60 detik, jadi jangan gunakan sebagai hitung mundur atau batas waktu. Durasi bergantung pada konten dan beban layanan; sampel bukan batas maksimum.
>
> Tinggi dan ukuran file bergantung pada konten. Satu sampel `long + 2K` berukuran `2048×46615` dan 63,9 MB; ini bukan batas keluaran. Hasil dapat melebihi 50 MB, jadi pertimbangkan biaya pengunduhan dan penampilan gambar besar.

## Penagihan

Setiap permintaan ditagih untuk satu gambar panjang pada tingkat keluaran yang dipilih, ditambah referensi: **harga tingkat keluaran + jumlah referensi × harga per referensi**. Gambar produk, gaya, dan subjek semuanya dihitung; referensi pertama juga dikenai biaya.

Ada 8 tingkat keluaran di bawah. Kunci harga: `kling-v4-long-image@<tingkat>` dan `kling-v4-long-image@input` untuk referensi. Dalam permintaan pembuatan, `resolution` tetap hanya menerima `1K` atau `2K`.

| Mode | Panjang | `1K` | `2K` |
| - | - | - | - |
| Halaman detail produk | `short` | `1K-SHORT` | `2K-SHORT` |
| Halaman detail produk | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Halaman detail produk | `long` | `1K-LONG` | `2K-LONG` |
| Desain halaman web | Hilangkan `length` | `1K-WEBPAGE` | `2K-WEBPAGE` |

Biaya dipotong saat pengiriman, diselesaikan saat berhasil, dan dikembalikan sepenuhnya saat gagal. Lihat [halaman harga](https://apimart.ai/pricing) untuk tarif dan diskon akun.

## Kesalahan umum

Kesalahan validasi ini mengembalikan HTTP 400 sinkron, tanpa tugas atau biaya pembuatan. Baca `error.message` untuk kesalahan pengiriman dan `data.error.message` untuk kegagalan setelah tugas dibuat.

| Cuplikan kesalahan | Penanganan |
| - | - |
| `` `prompt` is required for kling-v4-long-image `` | Berikan prompt yang tidak kosong. |
| `` `skill` is required for kling-v4-long-image `` | Berikan `skill`. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Gunakan `ecommerce` atau `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | Ecommerce memerlukan 1–3 gambar produk. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | Maksimal 3 gambar produk. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | Untuk ecommerce, gunakan `image_urls` dan hilangkan `image_with_roles`. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Gunakan `short`, `medium`, atau `long`. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Hilangkan `length` pada mode web. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | Untuk web, hilangkan `image_urls` dan gunakan `image_with_roles`. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Gunakan hanya `style` atau `subject`. |
| `kling-v4-long-image supports at most 1 image with role style` | Maksimal satu gambar per peran; subjek duplikat juga tidak valid. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Gunakan `1K` atau `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Hapus kolom ukuran, rasio, atau seri yang tidak didukung; jangan kirim `null` atau string kosong. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | Hilangkan `n` atau gunakan bilangan bulat `1`. |
| `reference image is not accessible for kling-v4-long-image` | Periksa akses publik, validitas URL, dan HTTP 403 / 404 / 410. |
| `unsupported reference image dimensions for kling-v4-long-image` | Kedua sisi minimal 300 px, rasio 2:5–5:2. |
| `reference image too large for kling-v4-long-image` | Maksimal 30 MB per referensi. |


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