Instrukcja integracji z API generowania filmów Kling

W tym dokumencie przedstawiono instrukcję integracji z API generowania filmów Kling, które umożliwia tworzenie oficjalnych filmów Kling na podstawie wprowadzonych parametrów.

Proces rejestracji

Aby korzystać z API, należy najpierw zarejestrować odpowiednią usługę na stronie Kling Videos Generation API. Po wejściu na stronę kliknij przycisk „Acquire”, jak pokazano na poniższym obrazku:

Jeśli nie jesteś zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, gdzie możesz się zarejestrować i zalogować. Po zalogowaniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. Przy pierwszym wniosku otrzymasz darmowy limit, który pozwala na bezpłatne korzystanie z API.

Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, który polega na wprowadzeniu słowa kluczowego prompt, działania action, adresu URL pierwszej klatki referencyjnej start_image_url oraz modelu model, aby uzyskać przetworzony wynik. Najpierw należy przesłać pole action o wartości text2video. Obsługiwane są trzy rodzaje działań: generowanie filmu z tekstu (text2video), generowanie filmu z obrazu (image2video) oraz rozszerzanie filmu (extend). Następnie należy wskazać model model. Obecnie dostępne modele to: kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1. Szczegóły przedstawiono poniżej:

Widzimy tutaj ustawienia nagłówków żądania (Request Headers), które obejmują:

accept: format odpowiedzi, tutaj application/json (format JSON).
authorization: klucz API do wywołania, który można wybrać z listy po rejestracji.

Dodatkowo ustawiono ciało żądania (Request Body), które zawiera:

model: model generujący film, dostępne modele to kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1.
mode: tryb generowania filmu, dostępne wartości to standardowy std, szybki pro oraz natywny 4K 4k. Tryb 4k jest obsługiwany tylko przez modele kling-v3 i kling-v3-omni i jest niekompatybilny z camera_control (kontrola ruchu kamery).
action: rodzaj zadania generowania filmu, obejmuje trzy typy: generowanie filmu z tekstu (text2video), generowanie filmu z obrazu (image2video), rozszerzanie filmu (extend).
start_image_url: w przypadku wyboru działania image2video wymagany jest link do pierwszej klatki referencyjnej.
end_image_url: opcjonalny link do ostatniej klatki w przypadku image2video.
duration: długość filmu w sekundach. Modele kling-v3 i kling-v3-omni obsługują elastyczną długość od 3 do 15 sekund (liczby całkowite), pozostałe modele obsługują 5 lub 10 sekund.
generate_audio: opcjonalnie, czy generować dźwięk synchronicznie, wartość boolean. Obsługiwane przez modele kling-v3, kling-v3-omni oraz kling-v2-6 (tylko tryb pro). Domyślnie false.
aspect_ratio: opcjonalny współczynnik proporcji filmu, obsługiwane wartości to 16:9, 9:16, 1:1, domyślnie 16:9.
cfg_scale: siła dopasowania do promptu, zakres [0,1], im większa wartość, tym bardziej zgodne z promptem.
camera_control: opcjonalne parametry kontroli ruchu kamery, obsługiwane są ustawienia typu type/simple oraz konfiguracje horizontal, vertical, pan, tilt, roll, zoom.
negative_prompt: opcjonalne słowa kluczowe, których nie chcemy w filmie, maksymalnie 200 znaków.
element_list: lista elementów referencyjnych, stosowana tylko w modelu kling-video-o1. Szczegóły użycia dostępne w dokumentacji oficjalnej.
video_list: lista filmów referencyjnych dostępnych przez URL, stosowana tylko w modelu kling-video-o1. Szczegóły w dokumentacji oficjalnej.
prompt: słowo kluczowe.
callback_url: URL do wywołania zwrotnego (callback).

Po wybraniu parametrów po prawej stronie wygenerowany zostanie odpowiedni kod, jak pokazano na obrazku:

Kliknij przycisk „Try”, aby przetestować, jak na powyższym obrazku. Otrzymamy następujący wynik:

{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}

W odpowiedzi znajduje się kilka pól, które opisano poniżej:

success: status zadania generowania filmu.
task_id: ID zadania generowania filmu.
video_id: ID wygenerowanego filmu.
video_url: link do wygenerowanego filmu.
duration: długość wygenerowanego filmu.
state: stan zadania generowania filmu.

Widzimy, że otrzymaliśmy satysfakcjonujące informacje o filmie. Wystarczy pobrać film Kling z adresu URL podanego w polu video_url. Jeśli chcesz wygenerować kod integracji, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:

curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

Macierz możliwości modeli

Różne modele różnią się obsługą parametrów. Poniższa macierz pochodzi z oficjalnej dokumentacji modeli video Kling. Przed wywołaniem sprawdź, czy kombinacja model / mode / duration obsługuje potrzebne funkcje, w przeciwnym razie API zwróci błędy takie jak model/mode/duration(...) is not supported with image_tail.

Model	Tryb	`end_image_url` (pierwsza i ostatnia klatka)	`generate_audio` (dźwięk)	`camera_control` (ruch kamery)	Uwagi
`kling-v1`	std / pro	✅ tylko `duration=5`	❌	✅ tylko `duration=5`	`extend` nie obsługuje `negative_prompt` i `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	Obsługa wielu obrazów i pełny tryb `extend`
`kling-v1-6`	pro	✅	❌	❌
`kling-v2-master`	—	❌	❌	❌	Jeden tryb, tylko `duration=5/10`
`kling-v2-1-master`	—	❌	❌	❌	Jeden tryb, tylko `duration=5/10`
`kling-v2-5-turbo`	std	❌	❌	❌
`kling-v2-5-turbo`	pro	✅	❌	❌
`kling-v2-6`	std	❌	❌	❌
`kling-v2-6`	pro	✅	✅	❌	Jedyny model poza v3 obsługujący dźwięk
`kling-v3`	std / pro	✅	✅	✅	`duration` od 3 do 15 sekund
`kling-v3`	4k	✅	✅	❌	Tryb 4K niekompatybilny z ruchem kamery
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-video-o1`	std / pro	✅	❌	❌	Obsługa tylko `duration=5/10`

Uwagi:

Tryb 4k jest obsługiwany tylko przez modele kling-v3 i kling-v3-omni i jest niekompatybilny z camera_control.
end_image_url można używać tylko w przypadku action=image2video wraz z start_image_url. Podanie tylko end_image_url bez start_image_url zostanie odrzucone.
Modele kling-v3 i kling-v3-omni akceptują dowolną długość duration od 3 do 15 sekund (liczby całkowite); pozostałe modele tylko 5 lub 10 sekund.
generate_audio domyślnie false. Obsługiwane tylko przez kling-v3, kling-v3-omni i kling-v2-6 (tryb pro).

Funkcja rozszerzania filmu

Jeśli chcesz kontynuować generowanie już wygenerowanego filmu Kling, ustaw parametr action na extend i podaj ID filmu, które można uzyskać zgodnie z podstawowym użyciem, jak pokazano na poniższym obrazku:

Widzimy, że ID filmu to:

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

Uwaga: video_id to ID wygenerowanego filmu. Jeśli nie wiesz, jak wygenerować film, zapoznaj się z sekcją podstawowego użycia.

Następnie musisz podać prompt do dalszej generacji filmu, można określić następujące parametry:

model: model generujący film, dostępne modele to kling-v1, kling-v1-5 i kling-v1-6.
mode: tryb generowania filmu, dostępne wartości to standardowy std, szybki pro oraz natywny 4K 4k (tylko kling-v3 i kling-v3-omni, niekompatybilne z kontrolą ruchu kamery).
duration: długość filmu, głównie 5 lub 10 sekund.
start_image_url: wymagany przy image2video, link do pierwszej klatki referencyjnej.
prompt: słowo kluczowe.

Przykład wypełnienia formularza:

Po wypełnieniu automatycznie wygenerowany zostanie kod:

Przykładowy kod Python:

import requests

url = "https://api.xhuoapi.ai/v1/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Po uruchomieniu otrzymamy wynik:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Wynik jest zgodny z poprzednim, co potwierdza funkcję rozszerzania filmu.

Asynchroniczne wywołanie zwrotne (callback)

Ponieważ generowanie filmów przez Kling Videos Generation API trwa stosunkowo długo (około 1-2 minut), a długie oczekiwanie na odpowiedź HTTP powoduje utrzymanie połączenia i zużycie zasobów systemowych, API oferuje wsparcie dla asynchronicznego wywołania zwrotnego. Proces jest następujący: klient wysyła żądanie z dodatkowym polem callback_url. API natychmiast zwraca odpowiedź zawierającą task_id – identyfikator zadania. Po zakończeniu generowania filmu wynik jest przesyłany metodą POST w formacie JSON na wskazany callback_url, zawierając również task_id, co pozwala powiązać zadanie z wynikiem. Poniżej przykład działania. Webhook to usługa HTTP odbierająca żądania. Programista powinien podać URL swojego serwera HTTP. Dla demonstracji użyto publicznej strony Webhook https://webhook.site/, gdzie po wejściu uzyskujemy unikalny URL webhooka, jak pokazano na obrazku:

Skopiuj ten URL, np. https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, i użyj jako callback_url. Ustaw odpowiednie parametry, jak na obrazku:

Po uruchomieniu otrzymasz natychmiast wynik:

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Po chwili na stronie https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 pojawi się wynik generowania filmu, jak na obrazku:

Zawartość:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Wynik zawiera pole task_id oraz pozostałe pola podobne do wcześniejszych, co pozwala powiązać zadanie z wynikiem.

Obsługa błędów

Podczas wywoływania API w przypadku błędów zwracane są odpowiednie kody i komunikaty, na przykład:

400 token_mismatched: Nieprawidłowe żądanie, możliwe brak lub błędne parametry.
400 api_not_implemented: Nieprawidłowe żądanie, możliwe brak lub błędne parametry.
401 invalid_token: Brak autoryzacji, nieprawidłowy lub brakujący token.
429 too_many_requests: Zbyt wiele żądań, przekroczono limit.
500 api_error: Błąd wewnętrzny serwera.

Przykład odpowiedzi błędu

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Podsumowanie

W tym dokumencie poznali Państwo sposób korzystania z API generowania filmów Kling, które umożliwia tworzenie filmów na podstawie promptu oraz pierwszej klatki referencyjnej. Mamy nadzieję, że dokumentacja pomoże w integracji i efektywnym wykorzystaniu API. W razie pytań prosimy o kontakt z zespołem wsparcia technicznego.

Documentation Index

​Proces rejestracji

​Podstawowe użycie

​Macierz możliwości modeli

​Funkcja rozszerzania filmu

​Asynchroniczne wywołanie zwrotne (callback)

​Obsługa błędów

​Przykład odpowiedzi błędu

​Podsumowanie