Utwórz zadanie Kling Motion Control

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

Użyj tego endpointu, aby utworzyć zadanie Motion Control na podstawie obrazu postaci i filmu referencyjnego.

Na tej stronie opisano zgodną trasę Motion Control. Kling Video 3.0 Motion Control korzysta z odrębnego kontraktu API.

Wymagane multimedia

image_url akceptuje publiczny adres URL lub nieprzetworzony ciąg Base64.

Użyj obrazu JPG, JPEG lub PNG o rozmiarze nie większym niż 10 MB.
Każdy wymiar obrazu musi mieścić się w zakresie od 300 do 65 536 pikseli.
Użyj proporcji obrazu w zakresie od 1:2,5 do 2,5:1.
Przesyłaj Base64 jako nieprzetworzony zakodowany ciąg bez data:image/...;base64, prefiksu.
Przedstaw jedną niezasłoniętą postać z kadrowaniem sylwetki zgodnym z ruchem referencyjnym.

video_url akceptuje publiczny adres URL pliku MP4 lub MOV.

Użyj filmu o rozmiarze nie większym niż 100 MB.
Ustaw krótszy bok na co najmniej 340 pikseli.
Ustaw dłuższy bok na nie więcej niż 3850 pikseli.
Użyj ciągłego ujęcia z jedną widoczną postacią.
Unikaj cięć, zmian kamery i nadmiernie szybkiego ruchu.

Przestrzegaj limitów czasu trwania i sprawdzaj zagnieżdżone pole terminalne task_status. Zewnętrzny kod HTTP 200 lub odpowiedź code: 0 potwierdzają odpowiedź na zapytanie, a nie pomyślny wynik generowania.

Ustaw wartość orientacji

character_orientation jest wymagana i akceptuje image lub video.

Wartość	Czas trwania filmu referencyjnego
`image`	3–10 sekund
`video`	3–30 sekund

Jeśli używasz element_list, ustaw character_orientation na video.

Wybierz model i tryb

Zgodna trasa akceptuje kling-v2-6 i kling-v3. Obie wartości modelu akceptują obie wartości trybu:

Model	`std`	`pro`
`kling-v2-6`	Akceptowane	Akceptowane
`kling-v3`	Akceptowane	Akceptowane

Jeśli pominiesz model_name, żądanie użyje kling-v2-6. Jeśli pominiesz mode, żądanie użyje std. Wartość kling-v3 zachowuje zgodną strukturę żądania opisaną na tej stronie; nie wybiera odrębnego kontraktu Kling 3.0 opartego na wersji ścieżki API. Zgodny kontrakt nie gwarantuje stałej rozdzielczości wyjściowej. Sprawdź każdy zwrócony film, jeśli aplikacja wymaga określonych wymiarów. keep_original_sound akceptuje yes lub no. Jeśli pominiesz to pole, żądanie użyje yes.

Przepływ zadania

Wyślij żądanie Motion Control

Wyślij obraz źródłowy, film referencyjny i wartość orientacji. Wybierz model, tryb i wartość dźwięku lub użyj ich udokumentowanych wartości domyślnych. Zapisz zwrócony task_id.

Odpytuj zadanie

Użyj Pobierz zadanie Kling ze zwróconym task_id. Kontynuuj, aż status będzie miał wartość succeed lub failed.

Zapisz wynik

Niezwłocznie pobierz i zapisz wynik. Dokumentacja zgodnego API Kling podaje, że wygenerowane filmy są usuwane po 30 dniach. Nie zakładaj, że zwrócony adres URL pozostanie dostępny przez pełne 30 dni.

Pola opcjonalne

Pole	Struktura	Ograniczenie
`prompt`	Ciąg znaków, maksymalnie 2500 znaków	Opcjonalne pole tekstowe w zgodnej strukturze żądania.
`callback_url`	Ciąg URI lub pusty ciąg	Pomiń pole albo użyj pustego ciągu, gdy nie skonfigurowano URI wywołania zwrotnego.
`external_task_id`	Ciąg znaków unikatowy dla Twojego konta	Łączy zadanie z aplikacją. Nie zastępuje zwróconego `task_id` w zapytaniach CometAPI.
`element_list`	Tablica zawierająca najwyżej jeden obiekt `{"element_id": 123}`	Łącz to pole tylko z `character_orientation: "video"`.
`watermark_info`	`{"enabled": boolean}`	Zgodna struktura znaku wodnego zawiera wyłącznie wartość `enabled` typu Boolean.

Struktura callbacka

Schemat callbacka Legacy ma następującą strukturę:

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

Status callbacka może mieć wartość submitted, processing, succeed lub failed. Pola wyniku końcowego są obecne tylko wtedy, gdy są zwracane dla stanu końcowego.

Pola wyniku

Pole	Typ	Opis
`task_result.videos[].id`	Ciąg znaków	Identyfikator wygenerowanego filmu.
`task_result.videos[].url`	Ciąg URI	Adres URL dostarczania wygenerowanego filmu.
`task_result.videos[].watermark_url`	Ciąg URI	Adres URL dostarczania filmu ze znakiem wodnym, jeśli zadanie taki zwróci.
`task_result.videos[].duration`	Ciąg znaków	Czas trwania wygenerowanego filmu w sekundach.
`final_unit_deduction`	Ciąg znaków	Końcowa wartość potrącenia jednostek zwrócona wraz z zadaniem.
`final_balance_deduction`	`{"quota": string, "list_price": string}`	Końcowe wartości potrąceń z salda zwrócone wraz z zadaniem.

Status zadania może mieć wartość submitted, processing, succeed lub failed.

Zobacz dokumentację referencyjną API Kling Motion Control oraz protokół callback Kling aby uzyskać szczegóły API.

Autoryzacje

Authorization

string

header

wymagane

Bearer authentication. Use your CometAPI API key.

Treść

application/json

image_url

string

wymagane

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>

wymagane

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>

wymagane

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.

Dostępne opcje:

image,

video

model_name

enum<string>

domyślnie: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.

Dostępne opcje:

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>

domyślnie:yes

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

Dostępne opcje:

yes,

no

mode

enum<string>

domyślnie:std

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

Dostępne opcje:

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

Odpowiedź

200 - application/json

Task accepted.

code

integer

wymagane

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

message

string

wymagane

Response message.

data

object

wymagane

Show child attributes

Utwórz zadanie Kling image-to-video

Poprzedni

Utwórz zadanie wideo Kling z wielu obrazów

Następny

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

Moderacja treści

Klucze API

Wymagane multimedia

Ustaw wartość orientacji

Wybierz model i tryb

Przepływ zadania

Pola opcjonalne

Struktura callbacka

Pola wyniku

Autoryzacje

Treść

Odpowiedź

​Wymagane multimedia

​Ustaw wartość orientacji

​Wybierz model i tryb

​Przepływ zadania

​Pola opcjonalne

​Struktura callbacka

​Pola wyniku

Autoryzacje

Treść

Odpowiedź

Wymagane multimedia

Ustaw wartość orientacji

Wybierz model i tryb

Przepływ zadania

Pola opcjonalne

Struktura callbacka

Pola wyniku