Kling Motion Control görevi oluşturma

POST

kling

videos

motion-control

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

Bu endpoint’i, bir karakter görselinden ve bir referans videosundan Motion Control görevi oluşturmak için kullanın.

Bu sayfa uyumlu Motion Control rotasını açıklar. Kling Video 3.0 Motion Control ayrı bir API sözleşmesi kullanır.

Gerekli medya

image_url genel bir URL’yi veya ham bir Base64 dizesini kabul eder.

10 MB veya daha küçük bir JPG, JPEG ya da PNG görseli kullanın.
Her görsel boyutunu 300 ile 65.536 piksel arasında tutun.
1:2,5 ile 2,5:1 arasında bir en-boy oranı kullanın.
Base64’ü ham kodlanmış dize olarak, bir data:image/...;base64, öneki olmadan gönderin.
Hareket referansıyla eşleşen vücut kadrajına sahip, engellenmemiş tek bir karakter gösterin.

video_url genel bir MP4 veya MOV URL’sini kabul eder.

100 MB veya daha küçük bir video kullanın.
Kısa kenarı en az 340 piksel yapın.
Uzun kenarı en fazla 3850 piksel yapın.
Görünür tek bir karakter içeren kesintisiz bir çekim kullanın.
Kesintilerden, kamera değişikliklerinden ve aşırı hızlı hareketlerden kaçının.

Süre sınırlarına uyun ve iç içe terminal task_status değerini inceleyin. Bir dış HTTP 200 veya yanıt code: 0, başarılı bir üretim sonucunu değil, sorgu yanıtını doğrular.

orientation değerini ayarlayın

character_orientation zorunludur ve image veya video değerlerini kabul eder.

Değer	Referans video süresi
`image`	3–10 saniye
`video`	3–30 saniye

element_list kullanırsanız character_orientation değerini video olarak ayarlayın.

Modeli ve modu seçin

Uyumlu rota kling-v2-6 ve kling-v3 değerlerini kabul eder. Her iki model değeri de her iki mod değerini kabul eder:

Model	`std`	`pro`
`kling-v2-6`	Kabul edilir	Kabul edilir
`kling-v3`	Kabul edilir	Kabul edilir

model_name değerini atlarsanız istek kling-v2-6 değerini kullanır. mode değerini atlarsanız, istek std değerini kullanır. kling-v3 değeri, uyumlu istek biçimini bu sayfada açıklandığı şekilde korur; ayrı Kling 3.0 yol-sürüm sözleşmesini seçmez. Uyumlu sözleşme sabit bir çıktı çözünürlüğünü garanti etmez. Uygulamanız belirli boyutlar gerektiriyorsa döndürülen her videoyu inceleyin. keep_original_sound yes veya no değerlerini kabul eder. Bu alanı atlarsanız istek yes değerini kullanır.

Görev akışı

Motion Control isteğini gönderin

Kaynak görseli, referans videosunu ve orientation değerini gönderin. Bir model, mod ve ses değeri seçin veya belgelenmiş varsayılanlarını kullanın. Döndürülen task_id değerini saklayın.

Görevi sorgulayın

Şunu kullanın: Bir Kling görevi alma döndürülen task_id ile. Durum succeed veya failed olana kadar devam edin.

Sonucu saklayın

Sonucu hemen indirin ve saklayın. Kling’in uyumlu API belgeleri, üretilen videoların 30 gün sonra silindiğini belirtir. Döndürülen URL’nin 30 günün tamamı boyunca erişilebilir kalacağına güvenmeyin.

İsteğe bağlı alanlar

Alan	Yapı	Kısıtlama
`prompt`	Dize, en fazla 2500 karakter	Uyumlu istek yapısındaki isteğe bağlı metin alanı.
`callback_url`	URI dizesi veya boş dize	Geri çağırma URI’si yapılandırılmadığında alanı atlayın ya da boş dize kullanın.
`external_task_id`	Hesabınız için benzersiz dize	Görevi uygulamanızla ilişkilendirir. CometAPI sorguları için döndürülen `task_id` değerinin yerine geçmez.
`element_list`	En fazla bir `{"element_id": 123}` nesnesi içeren dizi	Bu alanı yalnızca şununla birlikte kullanın `character_orientation: "video"`.
`watermark_info`	`{"enabled": boolean}`	Uyumlu filigran yapısı yalnızca `enabled` Boolean değerini içerir.

Geri çağırma yapısı

Legacy geri çağırma şeması aşağıdaki yapıya sahiptir:

{
  "task_id": "<task_id>",
  "task_status": "succeed",
  "task_status_msg": "",
  "created_at": 1785398400000,
  "updated_at": 1785398460000,
  "final_unit_deduction": "<value>",
  "final_balance_deduction": {
    "quota": "<value>",
    "list_price": "<value>"
  },
  "task_info": {
    "external_task_id": "<your_unique_id>"
  },
  "task_result": {
    "videos": [
      {
        "id": "<video_id>",
        "url": "https://media.example.com/<file_id>.mp4",
        "duration": "6.4"
      }
    ]
  }
}

Geri çağırma durumu submitted, processing, succeed veya failed olabilir. Terminal sonuç alanları yalnızca terminal durum için döndürüldüklerinde bulunur.

Sonuç alanları

Alan	Tür	Açıklama
`task_result.videos[].id`	Dize	Üretilen video kimliği.
`task_result.videos[].url`	URI dizesi	Üretilen videonun teslim URL’si.
`task_result.videos[].watermark_url`	URI dizesi	Görev bir tane döndürdüğünde filigranlı videonun teslim URL’si.
`task_result.videos[].duration`	Dize	Üretilen videonun saniye cinsinden süresi.
`final_unit_deduction`	Dize	Görevle birlikte döndürülen nihai birim kesinti değeri.
`final_balance_deduction`	`{"quota": string, "list_price": string}`	Görevle birlikte döndürülen nihai bakiye kesinti değerleri.

Görev durumu submitted, processing, succeed veya failed olabilir.

Şunlara bakın: Kling Motion Control API referansı ve Kling geri çağırma protokolü API ayrıntıları için.

Yetkilendirmeler

Authorization

string

header

gerekli

Bearer authentication. Use your CometAPI API key.

Gövde

application/json

image_url

string

gerekli

Character image as a public URL or a raw Base64 string. Send raw Base64 without a data:image/...;base64, prefix; data-URI input is outside the compatible contract. Supported formats are JPG, JPEG, and PNG. The image must be 10 MB or smaller. Its width and height must each be from 300 through 65,536 pixels, and its aspect ratio must be between 1:2.5 and 2.5:1.

video_url

string<uri>

gerekli

Public reference motion video URL. Use an MP4 or MOV file that is 100 MB or smaller. The short edge must be at least 340 pixels, and the long edge must not exceed 3850 pixels. The video must be at least 3 seconds long. The maximum duration depends on character_orientation.

character_orientation

enum<string>

gerekli

Required compatible string enum. With image, the reference video can be 3 to 10 seconds long. With video, the reference video can be 3 to 30 seconds long.

Mevcut seçenekler:

image,

video

model_name

enum<string>

varsayılan:kling-v2-6

Model ID for this compatible Motion Control request. Omit this field to use kling-v2-6. The kling-v3 value keeps this compatible request shape; it does not select the separate Kling 3.0 path-version contract.

Mevcut seçenekler:

kling-v2-6,

kling-v3

prompt

string

Optional text field in the compatible request structure. Maximum 2500 characters.

Maximum string length: 2500

keep_original_sound

enum<string>

varsayılan:yes

Compatible string enum. Accepted values are yes and no. Omitted requests use yes.

Mevcut seçenekler:

yes,

no

mode

enum<string>

varsayılan:std

Both compatible models accept std and pro. Omitted requests use std.

Mevcut seçenekler:

std,

pro

callback_url

Optional callback field in the compatible structure. Provide a URI, or omit the field or send an empty string when no callback URI is configured.

external_task_id

string

Optional ID for correlation in your application. The value must be unique for your account. Store the returned task_id for CometAPI status queries.

element_list

object[]

Optional compatible Element structure. Provide at most one object, and combine this field only with character_orientation: video.

Maximum array length: 1

Show child attributes

watermark_info

object

Optional compatible watermark structure.

Show child attributes

Yanıt

200 - application/json

Task accepted.

code

integer

gerekli

Response code. A value of 0 indicates that the request was accepted.

message

string

gerekli

Response message.

data

object

gerekli

Show child attributes

Son değiştirilme tarihi 31 Temmuz 2026

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

İçerik moderasyonu

API anahtarları

Kling Motion Control görevi oluşturma

Gerekli medya

orientation değerini ayarlayın

Modeli ve modu seçin

Görev akışı

İsteğe bağlı alanlar

Geri çağırma yapısı

Sonuç alanları

Yetkilendirmeler

Gövde

Yanıt

​Gerekli medya

​orientation değerini ayarlayın

​Modeli ve modu seçin

​Görev akışı

​İsteğe bağlı alanlar

​Geri çağırma yapısı

​Sonuç alanları

Yetkilendirmeler

Gövde

Yanıt

Gerekli medya

orientation değerini ayarlayın

Modeli ve modu seçin

Görev akışı

İsteğe bağlı alanlar

Geri çağırma yapısı

Sonuç alanları