Kling 3.0 API: Geçiş Rehberi, Hareket Kontrolü ve Kod

Kling 2.6 ile çalışan bir isteği yalnızca model adını değiştirerek güvenle Kling 3.0’a taşıyamazsınız. Kling 3.0 artık resmen kullanıma açık; ancak V3, Turbo, Omni ve Motion Control rotalarının yetenekleriyle şemaları birbirinden farklı. En güvenli geçiş yöntemi önce doğru rotayı seçmek, ardından ses, multi-shot ve referans kontrollerini tek tek eklemektir.

Koda geçmeden önce doğru endpoint’i seçin

Kling’in resmi VIDEO 3.0 rehberine göre 3.0, VIDEO 2.6 ve VIDEO O1’in halefi konumunda. VIDEO 2.6, VIDEO 3.0’a; VIDEO O1 ise VIDEO 3.0 Omni’ye yükseltiliyor. Geliştirici API’si modele özel ayrı operasyonlar sunduğu için “Kling 3.0 API” tek bir evrensel istek gövdesinden ibaret değil, bir erişim ailesi olarak düşünülmeli.

En sık karşılaşılan entegrasyon hatası, bir sağlayıcının kolaylaştırılmış şemasıyla Kling’in doğrudan şemasını birbirine karıştırmak. Krea’nın barındırılan isteği çalışan bir örnektir; aynı URL veya alanların resmi Kling geliştirici dokümantasyonu için de geçerli olduğunu kanıtlamaz.

Rotaları daha geniş bir çerçevede incelemek için Kling API entegrasyon rehberine göz atabilirsiniz. Bu yazı ise Kling 3.0’a geçişe ve endpoint davranışına odaklanıyor.

Kling 2.6’dan 3.0’a geçerken neler değişiyor?

Kling’in birinci taraf model rehberinde öne çıkan yükseltme yalnızca daha yüksek bir çözünürlük seçeneği değil; kontrol, süreklilik ve görsel-işitsel yönlendirme alanlarında geliyor. Aşağıdaki tablo, Kling’in model ailesi için açıkladığı yetenekler temel alınarak hazırlandı.

Pratikteki fark şu: 2.6 entegrasyonunda tek bir kısa prompt’la sınırlı kalan üretim, 3.0’da yönlendirilmiş bir sekansa dönüşebiliyor. Kling rehberi ayrıca kamera hareketi sırasında karakterlerin, nesnelerin ve sahne ayrıntılarının daha iyi korunabildiğini iddia ediyor; ancak bağımsız bir tutarlılık karşılaştırması yayımlamıyor. Bu iddiayı, uygulamanızın gerçek kullanımda ölçebileceği sonuçlardan ayrı değerlendirin.

Çalışan en küçük async Krea entegrasyonunu kurun

Video üretimi asenkron çalışır. Uygulamanız işi göndermeli, görev kimliğini saklamalı, durumu sorgulamalı veya bir callback almalı ve tamamlanan çıktıyı kalıcı olarak kaydetmelidir. Model render alırken ilk HTTP isteğini açık tutmayın.

Aşağıdaki örnekte, istek ve iş alanları yayımlanmış Kling 3.0 API rehberinde görülebildiği için Krea’nın herkese açık dokümante edilmiş Kling 3.0 endpoint’i kullanılıyor. Sağlayıcıya özel URL ve alanları ancak kullanmayı planladığınız resmi Kling şemasını kontrol ettikten sonra değiştirin.

Üretim işini gönderin

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

Krea’nın dokümante ettiği yanıtta job_id ve scheduled gibi başlangıç durumlarından biri bulunuyor. Sağlayıcının örneğinde durum kontrolleri için ayrı bir iş sorgulama endpoint’i kullanılıyor. Veritabanınızda polling başlamadan önce iş kimliğini kendi sipariş ID’nizle birlikte kaydedin.

Zaman aşımıyla polling yapın ve çıktıyı kaydedin

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Krea’nın örneklerinde üretim süreleri 51 saniye ve 2 dakika 3 saniye olarak verilmiş. Bu nedenle sabit bir Kling üretim süresi vaat etmek yerine kuyruk durumunu hesaba katan zaman aşımı değerleri kullanın.

Üretim ortamında webhook kullanmak, sürekli polling ihtiyacını ortadan kaldırabilir. Gelen iş ID’sini sisteminizin oluşturduğu bir işle karşılaştırın, handler’ı idempotent tasarlayın ve imzasız bir callback’i tek başına kimlik doğrulama kanıtı olarak kabul etmeyin.

3.0 kontrollerini tek tek ekleyin

Parametre adları, doğrudan Kling API’si ile barındırılan sağlayıcılar arasında değişebilir. Sağlayıcıya özel JSON’un uygulamanızın her yerine yayılmasına izin vermek yerine küçük bir uyumluluk katmanı oluşturun.

Resmi rehber; yerel ses üretimini, element referanslarını, multi-shot anlatıları ve beş diyalog dilini destekliyor. Ancak seçtiğiniz API endpoint’i, model ailesi seviyesinde sunulan bu özelliklerin yalnızca bir bölümünü dışarı açabilir.

Özel bir multi-shot payload’ı

Krea’nın dokümante edilmiş şemasında zamanlanmış multi_prompt bölümleri kullanılıyor. Barındırılan bir entegrasyon için bu yaklaşım işlevsel bir örnek oluşturuyor:

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

Üst düzeydeki toplam sürenin, bölümlerin süreleriyle aynı olduğunu doğrulayın. Krea, üç bölümden ve toplam 12 saniyeden oluşan bir testte 12.04 saniyelik sonuç bildirmiş. Bu nedenle dosya süresinin milisaniye düzeyinde matematiksel olarak tam çıkacağını varsaymayın.

Krea’da her bölüm 512 karakterle sınırlı ve yönlendirilmiş sekansın tamamı 15 saniyeyi geçemiyor. Her bölümü uzun bir sahne kompozisyonu gibi değil; özne, değişim ve kamera bilgisini içeren bir shot yönergesi olarak yazın. Doğrudan Kling rotanız resmi shot sözdizimini kullanıyorsa aynı zaman çizelgesi modelini koruyup payload’ı adapter sınırında dönüştürün.

Ses ve dil kısıtları

Resmi rehber, Çince, İngilizce, Japonca, Korece ve İspanyolcayı desteklenen diyalog dilleri arasında sayıyor; lehçeleri, aksanları, karaktere özel diyalogları ve farklı dillerin aynı sahnede kullanılmasını da açıklıyor. Desteklenmeyen diyalog girdilerinin İngilizceye çevrildiğini belirtiyor. Bu nedenle çok dilli uygulamalarda her kaynak dilin olduğu gibi korunacağını varsaymayın.

Ses aynı zamanda bir maliyet kararı. Krea’nın yayımladığı fiyatlarda std için ses olmadan saniye başına $0.1764, sesle birlikte $0.2646; pro için ses olmadan $0.2352, sesle birlikte $0.3528 ücret belirtiliyor. Listelenen 4K fiyatı ise ses olsun veya olmasın saniye başına $0.441. Bunlar Krea fiyatlarıdır; evrensel bir Kling API tarifesi olarak değerlendirilmemeli.

Mantıklı bir çalışma akışı önce sessiz taslaklar üretmek, ardından final için std veya pro adayında sesi etkinleştirmektir.

Üretim sınırı: maliyet, hız ve hata yönetimi

Kling’in resmi tüketici rehberinde VIDEO 3.0 için native audio olmadan 720p’de saniye başına 6 kredi, native audio olmadan 1080p’de saniye başına 8 kredi, sesli 720p’de saniye başına 9 kredi ve sesli 1080p’de saniye başına 12 kredi belirtiliyor. Voice Control ise saniye başına 2 kredi ekliyor. Bu rakamlar ilgili rehber içindeki göreli maliyeti gösterir; güncel geliştirici fiyatlandırma sayfasını kontrol etmeden bunları geliştirici API’si için dolar fiyatına çevirmeyin.

Doğrudan seçim yalnızca “hangi model daha ucuz?” sorusundan ibaret değil. Asıl karar, faturalandırma ve operasyon ihtiyaçlarıyla ilgili:

Hataları kategorilerine göre yönetin:

1. Geçici sağlayıcı hatalarını, üst sınırı belirlenmiş üstel geri çekilme yöntemiyle yeniden deneyin.
2. Geçersiz parametreleri, adapter payload’ı düzeltmeden yeniden göndermeyin.
3. Ağ zaman aşımının fark edilmeden yinelenen bir iş oluşturmasını önlemek için istemci tarafında bir idempotency anahtarı veya sipariş ID’si tutun.
4. Toplu üretimin etrafına kesin bir dolar veya kredi limiti koyun.
5. Sağlayıcının geçici URL’si süresi dolmadan önce sonucu kalıcı depolamaya indirin veya kopyalayın.
6. Model varyantını, süreyi, ses ayarını, çözünürlük seviyesini ve sağlayıcıyı birlikte log’layın; maliyet hesabı için yalnızca “Kling 3.0” bilgisi yeterli değildir.

Kling 2.6’dan 3.0’a geçiş kontrol listesi

1. Mevcut 2.6 çağrılarını envantere çıkarın. Model ID’lerini, görsel girdileri, başlangıç/bitiş karelerini, süreyi, sesi ve callback davranışını kaydedin.
2. 3.0 ailesindeki rotayı seçin. Prompt odaklı sinematik üretim için V3’ü, daha hızlı rota için Turbo’yu, O1 tarzı multimodal akış için Omni’yi, hareket referanslı çalışmalar için Motion Control’ü kullanın.
3. Bir sağlayıcı adapter’ı oluşturun. Doğrudan Kling, Krea ve diğer barındırılan şemaları ayrı çeviricilerin arkasında tutun.
4. Önce en küçük isteği taşıyın. Ses veya multi-shot kontrollerini eklemeden önce beş saniyelik, sessiz ve 16:9 bir üretimi test edin.
5. Her testte tek bir kontrol ekleyin. Önce süreyi, ardından sesi, sonra shot yönlendirmesini ve referansları doğrulayın. Böylece hatalı alanı izole etmek kolaylaşır.
6. Terminal durumlarını test edin. Başarılı sonuç, hata, iptal, zaman aşımı, yinelenen callback ve süresi dolmuş çıktı URL’si senaryolarını kapsayın.
7. Maliyetleri izleyerek gölge lansman yapın. Sabit bir prompt setini aynı süre ve çıktı seviyesiyle 2.6 ve 3.0’da karşılaştırın; ardından kalite veya kontrol kazanımının yeni rotayı haklı çıkarıp çıkarmadığına karar verin.

Geçiş, uygulamanız iş mantığını, faturalandırma kontrollerini veya sonuç işleme akışını değiştirmeden model ID’sini geri alabilecek duruma geldiğinde tamamlanmış sayılır.

Kling 3.0 API hakkında sık sorulan sorular

Resmi bir Kling 3.0 API var mı?

Evet. Kling’in resmi geliştirici dokümantasyonunda 3.0 modellerine özel API sayfaları bulunuyor ve Kling’in birinci taraf rehberi VIDEO 3.0’ı VIDEO 2.6’nın halefi olarak tanımlıyor. Bazı sayfalar istemci tarafında render edildiği için güncel geliştirici konsolundaki endpoint şemasını ayrıca incelemek gerekir.

Motion Control, Kling 3.0’ın bir parametresi mi?

Böyle olduğunu varsaymayın. Motion Control, Kling ekosisteminde kendi model sayfası bulunan özel amaçlı bir yetenek. Standart bir text-to-video isteğine doğrulanmamış motion_control alanı eklemek yerine, seçtiğiniz sağlayıcının dokümante ettiği operasyonu ve girdi şemasını kullanın.

Kling VIDEO 3.0 ne kadar uzun video üretebilir?

Kling’in resmi model rehberinde VIDEO 3.0’ın 3 ila 15 saniye arasında esnek çıktı üretebildiği belirtiliyor. Belirli bir barındırılan rota veya Turbo daha dar sınırlar uygulayabilir; bu nedenle seçtiğiniz endpoint’i doğrulayın.

Kling 3.0 native audio destekliyor mu?

Resmi VIDEO 3.0 rehberine göre evet. Rehberde karaktere özel diyaloglar, birden fazla dil, lehçeler ve aksanlar da açıklanıyor. Sesin isteğe bağlı olup olmadığı ve nasıl ücretlendirildiği endpoint’e veya sağlayıcının şemasına bağlı.

Kling 3.0 Omni, standart Kling 3.0 ile aynı mı?

Hayır. Kling, VIDEO 3.0’ı 2.6’nın; VIDEO 3.0 Omni’yi ise O1’in halefi olarak konumlandırıyor. Sağlayıcıların sayfalarında bu modeller farklı model ID’leriyle ve farklı referans ya da ses kontrolleriyle sunulabilir.

Kling web aboneliği API çağrılarını karşılar mı?

Güncel hesap dokümantasyonu aksini söyleyene kadar tüketici abonelikleriyle geliştirici API faturalandırmasını ayrı değerlendirin. API rotası genellikle kendi geliştirici hesabını, anahtarını ve faturalandırma kurulumunu gerektirir.

Geçişte izlenecek sınır aslında basit: 2.6 entegrasyonunun iş yaşam döngüsünü koruyun, modele özel adapter’ı değiştirin ve her yeni 3.0 kontrolünü onu gerçekten sunan rota üzerinde doğrulayın. Böylece en pahalı hata türünden kaçınabilirsiniz: isteği başarıyla gönderen ama arka planda yanlış varyantı, ses modunu veya faturalandırma seviyesini sessizce kullanan bir entegrasyon.