Panduan API Kling 4.0: Video Pertama Anda dengan Python dan cURL

API Kling 4.0 di PoYo memakai satu ID model, kling-4.0, untuk text-to-video, pembuatan dari frame pertama/terakhir, referensi visual, dan pengeditan video. Kirim permintaan, simpan ID tugasnya, lalu lakukan polling sampai tugas selesai. Panduan ini mengikuti skema PoYo saat ini, yang diperiksa pada 24 Oktober 2026; nama field dari penyedia lain tidak bisa dipertukarkan.

Buka playground Kling 4.0 untuk mencoba input secara visual, atau lihat dokumentasi API.

Membuat video pertama dengan cURL

Atur POYO_API_KEY di environment shell Anda, lalu kirim permintaan lima detik ini. Simpan kredensial di server, bukan di kode browser.

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",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Baca data.task_id dari respons JSON; pengiriman yang berhasil belum berarti videonya sudah jadi. Ganti YOUR_TASK_ID di bawah dengan nilai tersebut:

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

Status yang terdokumentasi adalah not_started, running, finished, dan failed. Setelah selesai, periksa data.files untuk menemukan file_url video. Jika gagal, periksa error_message dan simpan ID tugas untuk diagnosis. Melakukan polling pada tugas yang sudah ada tidak memerlukan pengiriman ulang.

Loop polling Python dengan batas waktu

Instal requests dan jalankan kode ini di backend Anda. Kode ini memeriksa error HTTP maupun error aplikasi, berhenti ketika tugas gagal, dan membatasi waktu tunggu hingga 30 menit. Timeout berarti Anda perlu memeriksa tugas yang sama nanti; mengulang pengiriman secara otomatis bisa membuat pekerjaan kedua yang ikut ditagih.

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(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
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":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

Pilih mode input yang tepat

Field video sumber akan memilih mode pengeditan meskipun gambar referensi juga disertakan. Untuk image-to-video, gambar pertama menetapkan frame awal; gambar kedua menentukan frame akhir. Gambar referensi memandu identitas atau gaya, dan maknanya tidak sama dengan frame batas.

Batas yang perlu divalidasi sebelum mengirim

Pembuatan video mendukung durasi bilangan bulat dari 3 hingga 30 detik, pada 720p atau 1080p. Prompt biasa dibatasi 26.000 karakter dalam skema PoYo ini. Setiap shot multi_prompt menerima hingga 512 karakter; durasi shot yang tidak diisi default ke lima detik. Total durasi shot harus 3–30 detik, dan durasi tingkat atas yang diisi secara eksplisit harus sama dengan total tersebut.

Referensi mengizinkan hingga 10 gambar, lima video, dan tujuh subjek, dengan batas gabungan 15 aset. Frame pertama dihitung dalam batas gambar sekaligus batas keseluruhan. Setiap video referensi atau subjek harus berdurasi 3–30 detik; total durasi nyata semuanya tidak boleh melebihi 30 detik. Jangan membulatkan durasi ke bawah agar input yang terlalu besar lolos validasi.

Memahami tagihan pertama

Permintaan lima detik 720p tanpa input video dikenai 142,5 kredit, atau $0.7125 berdasarkan konversi yang tercantum saat ini. Input video mengubah tarif sekaligus durasi yang ditagih. Lihat contoh harga sebelum memperkirakan biaya alur kerja video referensi atau pengeditan.

Produk kreator resmi mengiklankan kontrol tambahan, termasuk beberapa keyframe. Skema PoYo di sini menyediakan hingga dua frame batas dan prompt per shot; jangan kirim field rekaan seperti keyframes, seed, negative_prompt, atau generate_audio ke endpoint ini. Untuk contoh yang berfungsi, lanjutkan ke panduan prompt dan tutorial Omni Reference.

Pertanyaan yang sering diajukan

Apakah ID model API-nya kling-4-0? Bukan. Itu adalah slug halaman. ID model untuk permintaan adalah kling-4.0.

Bisakah saya meminta 4K di sini? Endpoint PoYo ini saat ini hanya menerima 720p dan 1080p. Periksa skema penyedia, jangan menyalin spesifikasi pemasaran dari aplikasi kreator.

Bisakah saya menggunakan callback? Permintaan submit mendukung callback_url di tingkat atas. Lihat dokumentasi terbaru untuk penanganan callback; contoh polling di atas tidak bergantung padanya.

Dari mana saya memulai? Gunakan permintaan teks saja yang singkat terlebih dahulu, simpan ID tugas dan hasilnya, lalu tambahkan satu modalitas input pada satu waktu di playground.