Kling API Entegrasyon Rehberi: Resmî Platform mu, Aggregator mı? (2026)

Kling ile video üretmek için herkese uyan tek bir API çağrısı yok. Kuaishou’nun video üretim modeli Kling; resmî Open Platform’un yanı sıra WaveSpeedAI, KIE ve fal gibi aggregator’lar üzerinden de sunuluyor. Her seçeneğin kimlik bilgileri, model kimlikleri, istek yapısı ve faturalandırması farklı. Değişmeyen kısım ise asenkron iş akışı: işi gönderin, ID’sini kaydedin, son durumu bekleyin ve kontrolsüz yeniden denemelere düşmeden çıktıyı alın.

SDK’dan önce hangi erişim yolunu kullanacağınıza karar verin

Kling’in resmî bir Open Platform’u var; ancak “Kling API” aramalarında bağımsız geçitler de karşınıza çıkar. Tercihinizi yalnızca model adına bakarak değil; sağlayıcı erişimi, entegrasyon hızı ve faturalandırmayı yönetme ihtiyacınıza göre yapın.

Çözünürlük bazlı fiyat ayrıntıları için mevcut Kling 3 API fiyatlandırma rehberine bakın. Bu yazıda fiyatı, ses çarpanlarını, eşzamanlılık değerlerini ve başarısız görev faturalandırmasını sağlayıcıya özel yapılandırma olarak ele alacağız.

Resmî Kling iş akışı nasıl ilerliyor?

Satın alma süreciniz doğrudan Kuaishou ile çalışmayı gerektiriyorsa veya birinci taraf model erişimine ihtiyaç duyuyorsanız resmî Open Platform’u kullanın. Güncel resmî dokümanlar; kimlik bilgisi kurulumu, görev oluşturma, callback’ler, eşzamanlılık kuralları ve hata kodlarını ayrı bölümlerde ele alıyor. Bu nedenle bir aggregator payload’ını uyarlamak yerine resmî akışı izleyin:

1. Kimlik doğrulama rehberinden resmî kimlik bilgisini oluşturun veya alın; token’ı yalnızca sunucu tarafında saklayın.
2. Resmî referansta gösterilen modele özel endpoint ve istek alanlarıyla belgelenmiş asenkron video görevini gönderin.
3. Durum bildirimleri almak istiyorsanız callback_url ekleyin. Belgelenen callback durumları submitted, processing, succeed ve failed; hata durumlarında task_status_msg değerini kaydedin.
4. Hesabınız için geçerli eşzamanlılık tahsisini kendi tarafınızda uygulayın. Resmî eşzamanlılık rehberi, aşırı yük durumunu Kling’in mutlaka kuyruğa alacağı işler olarak değil, HTTP 429 ve iş kodu 1303 olarak tanımlar.
5. Hatalı kimlik bilgileri, geçersiz parametreler, tükenen kaynaklar, politika engelleri ve yeniden denenebilir sunucu sorunlarını ayırmak için resmî hata kodu referansını kullanın.

Resmî kimlik doğrulama sayfası, erişilebilir doküman sürümünde istemci tarafında render ediliyor. Bu yüzden doğrulanmamış bir token oluşturma kodu burada tekrar edilmiyor. WaveSpeed, KIE ya da fal başlığının çalışacağını varsaymak yerine güncel kimlik bilgisi formatını doğrudan bu sayfadan alın.

Kesin payload’ı tahmin etmeden de resmî yaşam döngüsünü standartlaştırabilirsiniz:

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

Bu, kopyalayıp çalıştırılacak bir endpoint değil; yaşam döngüsü taslağıdır. Kesin token, yol, istek alanları ve yanıt zarfı için bağlantısı verilen resmî referansı kullanın.

Aggregator ne zaman daha mantıklı?

Kullandıkça öde erişimi, çok sayıda model için tek hesap veya sağlayıcı SDK’sı gerektiren prototiplerde aggregator’lar daha hızlı ilerlemenizi sağlayabilir. Ancak anahtarı, şemayı, kuyruğu, çıktı URL’sini ve bazı durumlarda saklama süresini onlar yönetir. Yeniden denemeden önce hatanın hangi katmanda oluştuğunu belirleyin.

Güvenle standartlaştırabileceğiniz Kling API sözleşmesi

Üretim ortamındaki istemciniz, sağlayıcı farklarını tek bir dahili fonksiyonun arkasına saklamalı. Hangi yolu seçerseniz seçin uygulamanızın şu adımları gerçekleştirmesi gerekir:

1. Kredi harcamadan önce prompt’u ve medya URL’lerini doğrulayın.
2. Sağlayıcıya özgü model ID’siyle video üretim görevi gönderin.
3. Dönen görev veya prediction ID’sini hemen kalıcı olarak kaydedin.
4. İş son duruma ulaşana kadar callback alın veya sonuç endpoint’ini sorgulayın.
5. Çıktı URL’sini, sağlayıcıyı, modeli, parametreleri ve maliyet metadatasını saklayın.
6. Sağlayıcı hata, iptal, zaman aşımı veya silinme bildirdiğinde yeniden denemeyi durdurun.

Soyutlama katmanınız örneğin şu normalize edilmiş nesneyi dönebilir:

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

Sağlayıcılar arasında taşınabilen parametreler

Kavramlar taşınabilir, alan adları değil. generate_audio, sound ve generate_audio: true, farklı servislerde birbiriyle ilişkili davranışları tanımlayabilir. Her sağlayıcının şemasını ayrı bir adapter olarak ele alın.

Sağlayıcılar arasında taşınmayan parametreler

İlk tuzak model ID’leridir. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video ve kwaivgi/kling-v3.0-std/text-to-video, birbirinin yerine geçebilecek değerler değil, farklı API rotalarını tanımlar.

Aynı durum kimlik doğrulama başlıkları, callback adları, sonuç URL’leri, görev durumu değerleri ve dosya yükleme kuralları için de geçerli. Örneğin completed durumunu sabitleyen bir istemci, başka bir sağlayıcının succeeded veya failed yanıtını yanlış sınıflandırabilir.

Üç farklı gerçek istek yapısı

Bu sağlayıcıya özel örnekler, evrensel bir Kling endpoint’inin neden olmadığını açıkça gösteriyor.

WaveSpeedAI: prediction ID ile sonuç sorgulama

WaveSpeedAI, Kling 3.0 Standard text-to-video için şu endpoint’i belgeliyor:

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

İstek Bearer token kullanır. Endpoint bir prediction ID döndürür; sonuç ise şu adresten alınır:

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

Minimum bir cURL akışı şöyle:

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

WaveSpeedAI model dokümanında 3–15 saniye aralığı, 16:9, 9:16 ve 1:1 oranları ile varsayılan 0.5 değerinde cfg_scale bulunuyor. Standard fiyat tablosunda, sessiz 5 saniyelik klip için $0.42; sesli sürüm için $0.63 yer alıyor. Bu rakamları evrensel Kling fiyatı olarak değil, sağlayıcı anlık görüntüsü olarak değerlendirin.

Üretimde, dar bir döngüde istek atmak yerine sonuç endpoint’ini backoff kullanarak sorgulayın. Bu endpoint için belgelenen son durumlar olan completed, failed, cancelled, timeout veya deleted görüldüğünde işlemi sonlandırın.

KIE: createTask ile callback veya görev sorgusu

KIE ortak bir görev oluşturma endpoint’i kullanıyor:

POST https://api.kie.ai/api/v1/jobs/createTask

Kling 3.0 model tanımlayıcısı kling-3.0/video; kimlik doğrulama ise Bearer token ile yapılıyor. Tek planlı, kompakt bir payload şöyle görünüyor:

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

KIE; 3–15 saniyelik videoları, 16:9, 9:16 ve 1:1 çıktı oranlarını, multi-shot modunda ise en fazla beş planı belgeliyor. Multi-shot girdilerinde her plan 1–12 saniye olarak belirlenebiliyor. Görsel öğelerde 2–4 adet JPG veya PNG URL’si kullanılabiliyor ve görsel başına belgelenen üst sınır 10 MB. Video öğelerinde ise en fazla 50 MB boyutunda tek bir MP4 veya MOV URL’si kullanılıyor.

Callback zorunlu değil, ancak KIE üretim kullanımı için öneriyor. Webhook’unuz uygun olduğunda imzayı doğrulamalı, hızlıca onay yanıtı vermeli ve görev sonucunu bir kuyruğa aktarmalı. Kaçırılan callback’ler için görev sorgulamasını kurtarma yolu olarak elinizde tutun.

KIE, yaygın hatalar için ayrı yanıt kodları belgeliyor: geçersiz kimlik doğrulama için 401, yetersiz kredi için 402, doğrulama hataları için 422 ve oran limitleri için 429. Kodu ve mesajı birlikte loglayın; genel bir “Kling başarısız oldu” kaydı, yeniden denemenin güvenli olup olmadığına karar vermek için yeterli değildir.

fal: model endpoint’i ve kuyruk istemcisi

fal, Kling 3.0’ı modele özel endpoint ID’leriyle sunuyor. Standard text-to-video için belgelenen ID şu:

fal-ai/kling-video/v3/standard/text-to-video

Ham API, Authorization: Key $FAL_KEY başlığını kullanıyor. Python ve JavaScript örnekleri, polling döngüsünü kendiniz yazmaktan genellikle daha kolay olan fal’in kuyruk farkındalıklı istemcisini kullanıyor.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

fal, 3–15 saniye aralığını, text-to-video için üç en-boy oranını ve varsayılanı 0.5 olan 0–1 aralığında bir cfg_scale değerini belgeliyor. Standard şemasına göre prompt ile multi_prompt alternatif alanlar: ikisini birden değil, yalnızca birini gönderin. Belgelenen generate_audio varsayılanı true; bütçeniz veya post-prodüksiyon süreciniz sessiz çıktı varsayıyorsa bu değeri açıkça belirtin.

fal ayrıca image-to-video ve motion-control için ayrı ID’ler belgeliyor. Güncel model referansını kontrol etmeden, yalnızca bir string içindeki text-to-video ifadesini değiştirerek bu ID’leri tahmin etmeyin.

Kotalar, kuyruk süresi ve kredi güvenliği

Resmî platform, WaveSpeedAI, KIE ve fal için geçerli tek bir herkese açık Kling kotası yok. Eşzamanlılık, oran limitleri, kredi bakiyeleri, başarısız görev ücretlendirmesi ve çıktı saklama süreleri seçtiğiniz erişim yoluna aittir. Bunları KLING_LIMIT adlı sabitler yerine sağlayıcı yapılandırması olarak saklayın.

Gerçek bir kullanıcı, operasyonel riski genel bir yeniden deneme önerisinden daha isabetli biçimde özetliyor:

“Kling, her üretim için ücret alıyor ve gerçek kuyruk gecikmeleri var. İlk kuracağım şey maliyet/eşzamanlılık sınırı olurdu; aksi halde kötü bir karede yeniden deneyen bir agent, kredilerinizi gece boyunca sessizce tüketebilir.” — X’te @ukrroot

Bütçe ve eşzamanlılık için koruma katmanları

Bir agent veya batch worker’ın Kling çağrısı yapmasına izin vermeden önce şu kontrolleri uygulayın:

1. Eşzamanlı iş üst sınırı: Her prompt için bir iş başlatmak yerine sağlayıcıya özel bir tavan belirleyin.
2. İş başına bütçe: Göndermeden önce süreyi, seviyeyi, sesi ve çıktı sayısını tahmin edin.
3. Yeniden deneme bütçesi: Aktarım hatalarını seçici biçimde tekrar deneyin; doğrulama, kimlik doğrulama veya yetersiz kredi hatalarını yeniden denemeyin.
4. İş defteri: Worker yeniden başladığında yinelenen üretim göndermemek için, her takip isteğinden önce sağlayıcı iş ID’sini kaydedin.
5. Son durum politikası: Sağlayıcı yeniden gönderimin güvenli olduğunu açıkça belirtmedikçe başarısız, iptal edilmiş, zaman aşımına uğramış veya silinmiş işleri tamamlanmış kabul edin.
6. Kredi alarmı: Bakiye veya öngörülen harcama bir eşiği geçtiğinde kuyruğu durdurun.
7. Anahtar ve çıktı güvenliği: Anahtarları sunucu tarafında tutun, açığa çıkan anahtarları hemen değiştirin ve tamamlanan videoları kalıcı depolamaya kopyalayın.

Beş saniyelik bir Standard test, 15 saniyelik Pro veya ses etkinleştirilmiş bir işe kıyasla ucuz olabilir; ancak “ucuz” kavramı sağlayıcıya özeldir. Varsayılan seviyeyi seçmeden önce canlı model sayfasını inceleyin.

Üretime çıkmadan önce izlemeniz gereken metrikler

Her istek için şu alanları takip edin:

Gecikme ve kotaları endpoint’e özgü kabul edin; herkese açık kaynaklar, sağlayıcılar arasında geçerli tek bir SLA sunmuyor.

Kling API hakkında sık sorulan sorular

Kling’in resmî bir API’si var mı?

Evet. Kling, resmî Open Platform geliştirici dokümantasyonu sunuyor. Resmî erişim yolu ile üçüncü taraf geçitler ayrı servislerdir; bu nedenle güncel kimlik bilgilerini, kotaları ve fiyatları Kling Open Platform dokümantasyonundan doğrulayın.

Tek ve evrensel bir Kling API endpoint’i var mı?

Hayır. Resmî platform, WaveSpeedAI, KIE ve fal farklı endpoint yolları, model ID’leri, kimlik doğrulama başlıkları ve yanıt zarfları kullanıyor. kling-3.0 değerinin her yerde geçerli olduğunu varsaymak yerine bir sağlayıcı adapter’ı oluşturun.

Polling mi, webhook mu kullanmalıyım?

Sağlayıcı destekliyorsa üretimde callback veya webhook kullanın; ancak yerel testler ve kaçırılan callback’leri telafi etmek için polling seçeneğini de koruyun. Geç gelen bir callback’in yinelenen kayıt oluşturmasını önlemek için exponential backoff, toplam bekleme sınırı ve idempotency ekleyin.

Hangi süreler ve en-boy oranları destekleniyor?

Güncel Kling 3.0 aggregator dokümanlarının birçoğu 3–15 saniyelik klipleri ve 16:9, 9:16, 1:1 oranlarını listeliyor. Endpoint’ler birbirinden farklı olabilir; bu değerleri birinci taraf ve evrensel sözleşme saymak yerine seçtiğiniz model sayfasına göre doğrulayın.

Sesi etkinleştirmek maliyeti değiştirir mi?

Çoğu durumda değiştirebilir. WaveSpeedAI, Kling 3.0 Standard endpoint’i için 1.5× ses çarpanı belgeliyor; fal ve KIE ise ses veya audio’yu istek parametresi olarak sunuyor. Seçtiğiniz endpoint’in canlı faturalandırma sayfasını kontrol edin ve bayrağı açıkça ayarlayın.

Yeniden deneme neden ek ücret oluşturdu?

İlk iş hâlâ kuyruktayken yapılan bir yeniden deneme ikinci bir üretim başlatabilir. İş ID’sini kalıcı olarak saklayın, eşzamanlılık sınırı kullanın, yalnızca geçici hataları yeniden deneyin ve belirsiz bir isteği tekrar göndermeden önce sağlayıcı faturalandırmasını uzlaştırın.

İlk üretime benzer testinizde bir adet 5 saniyelik, sessiz Standard iş çalıştırın ve tüm yaşam döngüsünü loglayın. Pro, ses, multi-shot veya eşzamanlılık özelliklerini ise ancak yinelenen worker işlemlerini doğru yönettiğinizden sonra ekleyin.