how-tos

Panduan Kling Image 4.0 API: Request Pertama dengan cURL dan Python

Poyo.ai Team
9 min read
Share:

Panduan Kling Image 4.0 API: request pertama dengan cURL dan Python

Panduan Kling Image 4.0 API ini membawa Anda dari API key hingga gambar jadi: satu panggilan cURL, loop polling Python yang dibatasi waktu, lalu body JSON yang berfungsi untuk setiap mode input kling-4.0-image dan kling-4.0-long-image. Coba semuanya terlebih dahulu di playground Kling Image 4.0; setiap body request di bawah mengikuti dokumentasi PoYo.

Request Kling Image 4.0 API pertama Anda dengan cURL

Buat key di dashboard PoYo dan simpan di server Anda sebagai POYO_API_KEY. Lalu kirim task text-to-image 2K:

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0-image",
    "input": {
      "prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
      "size": "16:9",
      "resolution": "2K"
    }
  }'

Respons berisi code: 200 dan data.task_id, dengan status: "not_started". Task yang sudah dikirim belum berarti gambar sudah jadi. Periksa dengan:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Status yang ada adalah not_started, running, finished, dan failed. Saat finished, data.files berisi satu entri per gambar dengan file_url dan file_type: "image", dan data.credits_amount menunjukkan biaya task. Saat failed, baca data.error_message.

Loop polling Python yang dibatasi waktu

Kode ini berjalan di backend Anda dengan requests. Kode memeriksa status HTTP dan field code di body (error validasi bisa datang sebagai HTTP 200 dengan code: 400), berhenti saat failed, dan berhenti menunggu setelah 20 menit tanpa mengirim ulang, karena submit kedua berarti tagihan kedua.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(resp):
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
    return body["data"]

def run(payload, max_wait=1200, every=10):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
        time.sleep(every)
    raise TimeoutError("still running, poll task " + task_id + " again later")

urls = run({
    "model": "kling-4.0-image",
    "input": {
        "prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
        "size": "1:1",
        "resolution": "2K",
    },
})
print(urls)

Untuk pekerjaan yang lama, tambahkan "callback_url": "https://your-domain.com/poyo-hook" di level atas payload. PoYo akan mengirim POST berisi data task yang sama (tanpa pembungkus code/data) ketika task selesai atau gagal, ditandatangani dengan HMAC-SHA256 di X-Webhook-Signature; dokumentasi webhook menjelaskan cara memverifikasinya.

Image-to-image dengan image_urls

Kirim 1 hingga 10 URL HTTP(S) publik di image_urls. Yang pertama adalah @Image1, yang kedua @Image2, sesuai urutan array. Beri setiap gambar peran di prompt dan sebutkan apa yang harus tetap tidak berubah.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "resolution": "2K"
  }
}

image_urls harus berupa array meskipun hanya untuk satu gambar. Setiap gambar maksimal 30 MB, lebar dan tinggi minimal 300 px, dengan rasio lebar/tinggi antara 0.4 dan 2.5.

Subjek konsisten dengan kling_elements

Sebuah element adalah satu karakter atau objek yang ditampilkan dari 2 hingga 4 sudut, dengan tampak depan lebih dulu. Element memerlukan setidaknya satu entri image_urls, dan Anda bisa mengirim hingga 7 element; jumlah gambar plus element dibatasi 10.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/character-front.png",
          "https://example.com/character-side.png",
          "https://example.com/character-back.png"
        ]
      }
    ],
    "resolution": "2K"
  }
}

Request ini berbiaya 13 kredit untuk gambar 2K ditambah 1 untuk gambar referensi dan 1 untuk element: 15 kredit ($0.075).

Set gambar dengan enable_sequential

Dengan enable_sequential: true, n berkisar 2 hingga 10 (default 4) dan model merencanakan gambar sebagai satu set dengan subjek dan gaya yang sama, dikembalikan sesuai urutan. Jika dimatikan, n dari 1 hingga 9 mengembalikan gambar-gambar independen.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
    "size": "3:2",
    "enable_sequential": true,
    "n": 4
  }
}

Dalam uji hari peluncuran kami (API produksi PoYo, 19 November 2026), satu set 16:9, 2K dengan n: 4 mengembalikan empat gambar 2720×1536 dengan pengendara, sepeda, dan pakaian yang sama pada fajar, siang, senja, dan malam. Biayanya 52 kredit dan memakan sekitar 4.9 menit dari submit hingga hasil.

Halaman webpage dan ecommerce panjang

Ganti ID model ke kling-4.0-long-image dan pilih skill. Desain webpage, opsional mengikuti referensi gaya:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
    "skill": "webpage",
    "style_image_url": "https://example.com/style-reference.png",
    "resolution": "2K"
  }
}

Halaman detail ecommerce dari satu foto produk:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
    "skill": "ecommerce",
    "image_urls": ["https://example.com/water-bottle.png"],
    "length": "medium",
    "resolution": "1K"
  }
}

Tips: sebutkan bahasa halaman. Dalam uji kami, prompt webpage berbahasa Inggris yang tidak menyebutkan bahasa untuk teks halaman justru menghasilkan teks berbahasa Mandarin. Menambahkan "All text on the page is in English." ke prompt memperbaikinya, itulah sebabnya kedua body di atas diakhiri dengan kalimat tersebut. Uji webpage 1K kami mengembalikan satu gambar 1024×4257 seharga 110 kredit dalam sekitar 1.7–2.2 menit.

image_urls dan length milik ecommerce; style_image_url dan subject_image_url milik webpage. Penjelasan lebih lanjut tentang panjang halaman dan output 8K ada di gambar 8K dan long image dengan Kling Image 4.0 API.

Menyimpan hasil

Setiap files[].file_url mengarah ke file PNG. Salin ke storage Anda sendiri alih-alih melakukan hot-link dari aplikasi Anda. Tiga hal dari pengujian hari peluncuran kami yang perlu diantisipasi:

  • Ukuran. Satu gambar 16:9 8K berupa PNG 10880×6144 berukuran sekitar 128 MB. Alirkan (stream) ke disk alih-alih memuatnya ke memori, dan naikkan read timeout klien Anda.
  • Kanal alpha. File unduhan berupa PNG RGBA bahkan untuk gambar yang tidak transparan. Jika pipeline, CDN, atau alur kerja cetak Anda mengharapkan RGB atau JPEG, konversikan setelah diunduh.
  • Urutan. Set gambar dikembalikan sesuai urutan, jadi indeks di files adalah nomor frame storyboard atau set slide Anda.

Aturan validasi yang perlu diperiksa sebelum submit

AturanModel
prompt 1–50,000 karakter, bukan hanya spasikeduanya
image_urls 1–10 item; masing-masing 30 MB, ≥300 px, rasio 0.4–2.5kling-4.0-image
kling_elements ≤ 7, masing-masing 2–4 URL, hanya bersama image_urls; gambar + element ≤ 10kling-4.0-image
n 1–9 tanpa set, 2–10 dengan enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" memerlukan 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Tidak ada field tambahan (output_format, seed, negative_prompt ditolak)keduanya

Error yang perlu ditangani

codeArtiYang harus dilakukan
400Parameter tidak validPerbaiki body; jangan coba ulang tanpa perubahan
401API key tidak ada atau tidak validPeriksa header
402Kredit tidak cukupIsi ulang, lalu kirim ulang
429Batas rateTunggu dan coba lagi nanti
500 / 502 / 503Error server atau upstreamUlangi submit dengan backoff

Task yang failed tidak ditagih, jadi mengirim ulang setelah kegagalan aman dilakukan. Mengirim ulang setelah timeout di sisi Anda tidak aman: lakukan polling pada task_id yang sama terlebih dahulu.

Cara menghitung tagihan pertama Anda

kling-4.0-image berbiaya harga per gambar dikali jumlah gambar, ditambah 1 kredit untuk setiap item image_urls dan setiap element, sekali per request. Dengan 1 kredit = $0.005:

RequestKreditUSD
Panggilan cURL pertama di atas (2K, satu gambar)13$0.065
Prompt yang sama pada 8K32$0.16
Edit dengan element di atas (2K, 1 gambar + 1 element)15$0.075
Set empat gambar 2K52$0.26
Webpage 1K, tanpa referensi110$0.55
Halaman ecommerce medium 1K, 1 foto produk95$0.475

Tabel lengkap dan contoh lainnya ada di harga Kling Image 4.0 API. Untuk ikhtisar kedua ID model, lihat Apa itu Kling Image 4.0.

Pertanyaan yang sering diajukan

Bagaimana cara memanggil Kling Image 4.0 API dengan Python? Kirim body JSON dengan POST ke https://api.poyo.ai/api/generate/submit menggunakan requests, baca data.task_id, lalu lakukan polling /api/generate/status/{task_id} hingga finished dan baca files[].file_url. Loop di atas melakukan ini dengan batas waktu dan pemeriksaan error.

Apa ID model Kling Image 4.0 API? kling-4.0-image untuk text-to-image, edit, dan set gambar, serta kling-4.0-long-image untuk halaman webpage dan ecommerce panjang. kling-4-0-image hanyalah slug halaman.

Apakah Kling Image 4.0 API mendukung webhook? Ya. Tambahkan callback_url di level atas request. PoYo mengirim POST yang ditandatangani saat task selesai atau gagal.

Bisakah saya mendapatkan output JPEG dari Kling Image 4.0 API? Tidak ada field format output; hasilnya PNG. File unduhan kami berupa PNG RGBA bahkan untuk gambar yang tidak transparan, jadi konversikan di sisi Anda jika memerlukan JPEG.

Mengapa long webpage Kling Image 4.0 saya keluar dalam bahasa lain? Jika prompt tidak menyebutkan bahasa untuk teks halaman, model bisa memilihnya sendiri. Sebutkan bahasanya, misalnya "All text on the page is in English."

Share: