how-tos

Kling Image 4.0 API Rehberi: cURL ve Python ile İlk İstek

Poyo.ai Team
8 min read
Share:

Kling Image 4.0 API rehberi: cURL ve Python ile ilk istek

Bu Kling Image 4.0 API rehberi sizi bir API anahtarından tamamlanmış bir görsele götürür: tek bir cURL çağrısı, süre sınırlı bir Python sorgulama döngüsü ve ardından kling-4.0-image ile kling-4.0-long-image modellerinin her girdi modu için çalışan bir JSON gövdesi. Hepsini önce Kling Image 4.0 playground'unda deneyebilirsiniz; aşağıdaki tüm istek gövdeleri PoYo dokümantasyonunu izler.

cURL ile ilk Kling Image 4.0 API isteğiniz

PoYo panelinde bir anahtar oluşturun ve sunucunuzda POYO_API_KEY olarak saklayın. Ardından 2K bir metinden görsele görevi gönderin:

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"
    }
  }'

Yanıtta code: 200 ve data.task_id bulunur, status: "not_started" ile. Gönderilmiş bir görev henüz tamamlanmış bir görsel değildir. Şu komutla kontrol edin:

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

Durumlar not_started, running, finished ve failed'dır. finished olduğunda data.files, her görsel için file_url ve file_type: "image" içeren bir kayıt tutar; data.credits_amount ise görevin maliyetini gösterir. failed olduğunda data.error_message alanını okuyun.

Süre sınırlı bir Python sorgulama döngüsü

Bu kod backend'inizde requests ile çalışır. Hem HTTP durumunu hem de gövdedeki code alanını kontrol eder (doğrulama hataları HTTP 200 ile code: 400 olarak gelebilir), failed durumunda durur ve 20 dakika sonra yeniden göndermeden beklemeyi bırakır, çünkü ikinci bir gönderim ikinci bir faturadır.

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)

Uzun işler için bunun yerine payload'un üst düzeyine "callback_url": "https://your-domain.com/poyo-hook" ekleyin. Görev tamamlandığında veya başarısız olduğunda PoYo aynı görev verisini (code/data sarmalayıcısı olmadan) X-Webhook-Signature içinde HMAC-SHA256 ile imzalanmış bir POST olarak gönderir; nasıl doğrulanacağını webhook dokümantasyonu gösteriyor.

image_urls ile görselden görsele

image_urls içinde 1 ila 10 herkese açık HTTP(S) URL'si gönderin. Dizi sırasına göre ilki @Image1, ikincisi @Image2'dir. Promptta her birine bir rol verin ve neyin değişmeden kalması gerektiğini söyleyin.

{
  "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 tek bir görsel için bile dizi olmalıdır. Her görsel en fazla 30 MB, genişlik ve yükseklikte en az 300 px olmalı ve genişlik/yükseklik oranı 0.4 ile 2.5 arasında kalmalıdır.

kling_elements ile tutarlı nesneler

Bir öğe, 2 ila 4 açıdan gösterilen tek bir karakter veya nesnedir; ön görünüm ilk sırada yer alır. Öğeler en az bir image_urls girdisi gerektirir ve en fazla 7 tane gönderebilirsiniz; görseller artı öğeler 10 ile sınırlıdır.

{
  "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"
  }
}

Bu istek 2K görsel için 13 kredi, referans görsel için 1 ve öğe için 1 kredi tutar: 15 kredi ($0.075).

enable_sequential ile görsel setleri

enable_sequential: true ile n 2'den 10'a kadar (varsayılan 4) olur ve model görselleri aynı nesneler ve stille tek bir set olarak planlayıp sıralı döndürür. Kapalıyken n 1'den 9'a kadar bağımsız görseller döndürür.

{
  "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
  }
}

Lansman günü testimizde (PoYo üretim API'si, 19 Kasım 2026) n: 4 ile 16:9, 2K bir set; şafak, öğle, gün batımı ve gece boyunca aynı sürücü, motosiklet ve kıyafete sahip dört adet 2720×1536 görsel döndürdü. Maliyeti 52 kredidir ve gönderimden sonuca yaklaşık 4.9 dakika sürdü.

Uzun web sayfaları ve e-ticaret sayfaları

Model kimliğini kling-4.0-long-image olarak değiştirin ve bir skill seçin. İsteğe bağlı olarak bir stil referansını izleyen bir web sayfası tasarımı:

{
  "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"
  }
}

Tek bir ürün fotoğrafından bir e-ticaret detay sayfası:

{
  "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"
  }
}

İpucu: sayfa dilini belirtin. Testimizde metnin hangi dilde olması gerektiğini söylemeyen İngilizce bir web sayfası promptu, sayfada Çince metinle döndü. Prompta "All text on the page is in English." eklemek sorunu çözdü; yukarıdaki iki gövdenin de bu satırla bitmesinin nedeni bu. 1K web sayfası testimiz yaklaşık 1.7–2.2 dakikada 110 krediye bir adet 1024×4257 görsel döndürdü.

image_urls ve length, ecommerce'e aittir; style_image_url ve subject_image_url, webpage'e aittir. Sayfa uzunlukları ve 8K çıktı hakkında daha fazlası Kling Image 4.0 API ile 8K ve uzun görseller yazısında.

Sonuçları kaydetme

Her files[].file_url bir PNG'yi gösterir. Uygulamanızdan doğrudan bağlantı vermek yerine kendi depolama alanınıza kopyalayın. Lansman günü çalıştırmamızdan, planlamanız gereken üç şey:

  • Boyut. Tek bir 16:9 8K görsel, yaklaşık 128 MB'lık 10880×6144 bir PNG'ydi. Belleğe yüklemek yerine diske akışla aktarın ve istemcinizin okuma zaman aşımını artırın.
  • Alfa kanalı. İndirilen dosyalar opak görseller için bile RGBA PNG'lerdi. Pipeline'ınız, CDN'iniz veya baskı iş akışınız RGB ya da JPEG bekliyorsa indirdikten sonra dönüştürün.
  • Sıra. Bir görsel seti sıralı döner; dolayısıyla files içindeki indeks, storyboard'unuzun veya slayt setinizin kare numarasıdır.

Göndermeden önce kontrol edilmesi gereken doğrulama kuralları

KuralModel
prompt 1–50,000 karakter, yalnızca boşluk olamazikisi de
image_urls 1–10 öğe; her biri 30 MB, ≥300 px, oran 0.4–2.5kling-4.0-image
kling_elements ≤ 7, her biri 2–4 URL, yalnızca image_urls ile; görseller + öğeler ≤ 10kling-4.0-image
n set olmadan 1–9, enable_sequential: true ile 2–10kling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" 1–3 image_urls gerektirir; resolution 1K / 2Kkling-4.0-long-image
Ek alan yok (output_format, seed, negative_prompt reddedilir)ikisi de

Ele alınması gereken hatalar

codeAnlamıNe yapmalı
400Geçersiz parametrelerGövdeyi düzeltin; değiştirmeden yeniden denemeyin
401Eksik veya geçersiz API anahtarıBaşlığı kontrol edin
402Yetersiz krediBakiye yükleyin, sonra yeniden gönderin
429Hız sınırıBekleyip daha sonra yeniden deneyin
500 / 502 / 503Sunucu veya üst sağlayıcı hatasıGönderimi backoff ile yeniden deneyin

failed bir görevden ücret alınmaz; bu yüzden bir hatadan sonra yeniden göndermek güvenlidir. Sizin tarafınızdaki bir zaman aşımından sonra yeniden göndermek ise güvenli değildir: önce aynı task_id'yi sorgulayın.

İlk faturanız nasıl hesaplanır

kling-4.0-image, görsel başına fiyatın görsel sayısıyla çarpımı artı istek başına bir kez her image_urls öğesi ve her öğe için 1 krediye mal olur. 1 kredi = $0.005 ile:

İstekKrediUSD
Yukarıdaki ilk cURL çağrısı (2K, tek görsel)13$0.065
Aynı prompt 8K'da32$0.16
Yukarıdaki öğe düzenlemesi (2K, 1 görsel + 1 öğe)15$0.075
Dört görsellik 2K set52$0.26
1K web sayfası, referanssız110$0.55
1K medium e-ticaret sayfası, 1 ürün fotoğrafı95$0.475

Tam tablolar ve daha fazla örnek Kling Image 4.0 API fiyatları yazısında. Her iki model kimliğine genel bakış için Kling Image 4.0 nedir yazısına bakın.

Sıkça sorulan sorular

Kling Image 4.0 API'yi Python ile nasıl çağırırım? JSON gövdesini requests ile https://api.poyo.ai/api/generate/submit adresine POST edin, data.task_id değerini okuyun, ardından finished olana kadar /api/generate/status/{task_id} uç noktasını sorgulayıp files[].file_url değerini okuyun. Yukarıdaki döngü bunu bir son tarih ve hata kontrolleriyle yapar.

Kling Image 4.0 API'nin model kimliği nedir? Metinden görsele, düzenlemeler ve görsel setleri için kling-4.0-image, uzun web sayfaları ve e-ticaret sayfaları için kling-4.0-long-image. kling-4-0-image yalnızca sayfa slug'ıdır.

Kling Image 4.0 API webhook destekliyor mu? Evet. İsteğin üst düzeyine callback_url ekleyin. Görev tamamlandığında veya başarısız olduğunda PoYo imzalı bir POST gönderir.

Kling Image 4.0 API'den JPEG çıktı alabilir miyim? Çıktı formatı alanı yoktur; sonuçlar PNG'dir. İndirdiğimiz dosyalar opak görseller için bile RGBA PNG'lerdi; JPEG gerekiyorsa kendi tarafınızda dönüştürün.

Kling Image 4.0 uzun web sayfam neden başka bir dilde geldi? Prompt sayfa metninin dilini belirtmezse model kendisi bir dil seçebilir. Dili belirtin, örneğin "All text on the page is in English."

Share: