Przejdź do głównej treści
W tym artykule przedstawiono instrukcję integracji Kling Videos Generation API, która umożliwia generowanie oficjalnych filmów Kling poprzez wprowadzanie niestandardowych parametrów.

Proces aplikowania

Aby korzystać z Kling Videos Generation API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go na później. Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania z zaproszeniem do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token może wywoływać wszystkie usługi platformy, bez konieczności osobnego aplikowania dla każdej usługi. Przy pierwszej aplikacji otrzymasz darmowy limit, który umożliwia bezpłatne wypróbowanie; gdy limit jest niewystarczający, możesz doładować uniwersalne saldo w konsoli.
📘 Pełna dokumentacja: Kling Videos Generation API →

Podstawowe użycie

Najpierw zapoznajmy się z podstawowym sposobem użycia, czyli wprowadzeniem promptu prompt, działania generowania action, referencyjnego obrazu pierwszej klatki start_image_url oraz modelu model, aby uzyskać przetworzony wynik. Najpierw należy po prostu przekazać pole action, którego wartością jest text2video; obejmuje ono głównie trzy działania: tekst na wideo (text2video), obraz na wideo (image2video), rozszerzanie wideo (extend), następnie musimy również wprowadzić model model, obecnie dostępne są głównie modele 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-o1, a szczegółowa treść jest następująca:

Można zobaczyć, że ustawiliśmy tutaj Request Headers, w tym:
  • accept: format odpowiedzi, który chcesz otrzymać, tutaj wpisz application/json, czyli format JSON.
  • authorization: klucz do wywoływania API, po uzyskaniu można go bezpośrednio wybrać z listy rozwijanej.
Dodatkowo ustawiono Request Body, w tym:
  • model: model do generowania wideo, obejmuje głównie modele 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-o1.
  • mode: tryb generowania wideo, dostępne wartości to tryb standardowy std, tryb ultraszybki pro oraz natywny tryb 4K 4k. Spośród nich 4k obsługuje wyłącznie kling-v3 i kling-v3-omni, a także nie jest kompatybilny z camera_control (kontrola ruchu kamery).
  • action: działanie tego zadania generowania wideo, obejmuje głównie trzy działania: tekst na wideo (text2video), obraz na wideo (image2video), rozszerzanie wideo (extend).
  • start_image_url: link do referencyjnego obrazu pierwszej klatki, który należy przesłać, gdy wybrano działanie obraz na wideo image2video.
  • end_image_url: opcjonalne podczas obrazu na wideo, określa ostatnią klatkę.
  • duration: długość wideo, w sekundach. kling-v3 i kling-v3-omni obsługują całkowity czas trwania od 3 do 15 sekund; kling-o1 obsługuje wyłącznie 5 sekund; inne modele obsługują 5 lub 10 sekund.
  • generate_audio: czy synchronicznie generować dźwięk, opcjonalne, wartość logiczna. Obsługiwane przez kling-v3, kling-v3-omni oraz kling-v2-6 (wyłącznie tryb pro). Domyślnie false.
  • aspect_ratio: proporcje wideo, opcjonalne, obsługuje 16:9, 9:16, 1:1, domyślnie 16:9.
  • cfg_scale: siła zgodności, zakres [0,1], im większa, tym lepiej odpowiada promptowi.
  • camera_control: opcjonalne, parametry obiektu do kontrolowania ruchu kamery, obsługuje ustawienia wstępne type/simple oraz konfiguracje takie jak horizontal, vertical, pan, tilt, roll, zoom.
  • negative_prompt: opcjonalne, negatywny prompt określający, co nie powinno się pojawić, maksymalnie 200 znaków.
  • image_list: lista obrazów referencyjnych Omni, dla modeli kling-o1 i kling-v3-omni, sposób użycia znajduje się poniżej w sekcji „Wszechstronne odniesienie Omni”.
  • video_list: lista referencyjnych filmów Omni (obsługuje edycję wideo), dla modeli kling-o1 i kling-v3-omni, sposób użycia znajduje się poniżej w sekcji „Wszechstronne odniesienie Omni”.
  • prompt: prompt.
  • callback_url: URL, na który należy zwrócić wynik wywołania zwrotnego.
  • async: opcjonalne, po ustawieniu na true interfejs natychmiast zwraca task_id, bez konieczności podawania callback_url, a następnie wynik jest pobierany przez odpytywanie odpowiedniego interfejsu zapytania o zadanie.
Po dokonaniu wyboru można zauważyć, że po prawej stronie również wygenerowano odpowiedni kod, jak pokazano na rysunku:

Kliknij przycisk „Try”, aby przeprowadzić test. Jak pokazano na powyższym rysunku, otrzymaliśmy tutaj następujący wynik:
Zwrócony wynik zawiera wiele pól, które opisano poniżej:
  • success, status zadania generowania wideo w tym momencie.
  • task_id, ID zadania generowania wideo w tym momencie.
  • video_id, ID wideo zadania generowania wideo w tym momencie.
  • video_url, link do wideo zadania generowania wideo w tym momencie.
  • duration, długość wideo zadania generowania wideo w tym momencie.
  • state, stan zadania generowania wideo w tym momencie.
Można zobaczyć, że otrzymaliśmy satysfakcjonujące informacje o wideo, wystarczy pobrać wygenerowane wideo Kling zgodnie z adresem linku do wideo data w wyniku. Ponadto, jeśli chcesz wygenerować odpowiedni kod integracji, możesz go bezpośrednio skopiować. Na przykład kod CURL jest następujący:

Macierz możliwości modeli

Różne modele znacznie różnią się pod względem obsługi parametrów. Poniższa macierz została opracowana na podstawie oficjalnej dokumentacji Kling video models. Przed wywołaniem najpierw sprawdź, czy bieżąca kombinacja model / mode / duration obsługuje wymaganą funkcję, w przeciwnym razie zostaną zwrócone błędy takie jak model/mode/duration(...) is not supported with image_tail. Uwagi:
  • mode=4k obsługują tylko kling-v3 i kling-v3-omni; ponadto jest on wzajemnie wykluczający się z camera_control (ruchem kamery).
  • end_image_url można używać tylko wraz z start_image_url, gdy action=image2video. Przekazanie wyłącznie end_image_url (bez start_image_url) zostanie odrzucone.
  • kling-v3 / kling-v3-omni akceptują dowolną całkowitą wartość duration od 3 do 15 sekund; kling-o1 akceptuje tylko 5; pozostałe modele akceptują tylko 5 lub 10.
  • Domyślna wartość generate_audio to false. Obsługują ją tylko kling-v3, kling-v3-omni i kling-v2-6 (tryb pro).

Funkcja rozszerzania wideo

Jeśli chcesz kontynuować generowanie już wygenerowanego wideo Kling, możesz ustawić parametr action na extend oraz wprowadzić ID wideo, które wymaga dalszego generowania. ID wideo uzyskuje się na podstawie podstawowego użycia, jak pokazano na poniższym obrazku:

W tym momencie można zobaczyć, że ID wideo to:
Uwaga, video_id w tym wideo jest ID wygenerowanego wideo. Jeśli nie wiesz, jak wygenerować wideo, możesz zapoznać się z podstawowym użyciem powyżej, aby wygenerować wideo.
Następnie musimy wypełnić podpowiedź wymaganą do rozszerzenia w następnym kroku, aby dostosować generowane wideo, i możemy określić następującą zawartość:
  • model: model do generowania wideo, głównie modele kling-v1, kling-v1-5 i kling-v1-6.
  • mode: tryb generowania wideo, opcjonalne wartości to tryb standardowy std, tryb ultraszybki pro i natywny tryb 4K 4k (obsługiwany tylko przez kling-v3 i kling-v3-omni, niekompatybilny z kontrolą ruchu kamery).
  • duration: długość wideo dla tego zadania generowania wideo, obejmuje głównie 5 s i 10 s.
  • start_image_url: link do referencyjnego obrazu pierwszej klatki, który należy przesłać, gdy wybrano działanie generowania wideo z obrazu image2video.
  • prompt: podpowiedź.
Przykład wypełnienia jest następujący:

Po wypełnieniu kod zostanie wygenerowany automatycznie w następujący sposób:

Odpowiedni kod Python:
Kliknij uruchom, a okaże się, że otrzymasz wynik jak poniżej:
Można zauważyć, że zawartość wyniku jest zgodna z powyższą, co realizuje funkcję rozszerzania wideo.

Omni — wszechstronne referencje (edycja wideo / referencyjne wideo / referencje wieloobrazowe)

kling-o1 i kling-v3-omni to dwa niezależne modele, oba obsługujące funkcję „wszechstronnych referencji”. Na podstawie generowania wideo z tekstu (action=text2video) można dodatkowo przekazać referencyjne obrazy lub referencyjne wideo, aby zrealizować referencje wieloobrazowe, referencyjne wideo oraz bezpośrednią edycję istniejącego wideo. Główna konwencja: materiały referencyjne muszą być przywołane w prompt w postaci &lt;&lt;<image_1>>>, &lt;&lt;<video_1>>> (numeracja rozpoczyna się od 1), aby odwoływać się do materiałów na odpowiednich pozycjach w image_list / video_list; tylko wtedy model zastosuje te referencje. Jeśli zostaną przekazane tylko materiały bez przywołania ich w podpowiedzi, materiały zostaną zignorowane.
Informacja dotycząca bezpieczeństwa: bieżące API nie udostępnia element_list. ID biblioteki Kling Element Library nie są izolowane między dzierżawcami; przed udostępnieniem API zarządzania elementami z izolacją między dzierżawcami, użyj image_list, aby przekazać referencyjny obraz obiektu.
Omni request nie obsługuje negative_prompt, cfg_scale ani camera_control, a także nie można używać mode=4k. Gdy zawiera referencyjne wideo, generate_audio musi mieć wartość false.

Referencyjne wideo i edycja wideo (video_list)

video_list służy do przekazywania referencyjnych filmów wideo i jest najczęściej używanym scenariuszem tej funkcji. Pola elementów tablicy są następujące:
  • video_url: link do referencyjnego filmu wideo, nie może być pusty. Maksymalnie 1 film MP4/MOV, rozmiar pliku ≤200MB, liczba klatek 24–60fps. kling-o1 wymaga długości 3–10 sekund oraz szerokości i wysokości po 700–2160px; kling-v3-omni wymaga długości 3–15,5 sekundy, szerokości i wysokości po 700–4553px, łącznej liczby pikseli ≤8 294 400 oraz proporcji obrazu 0,4–2.
  • refer_type: typ referencji, opcjonalnie base (domyślnie, bazowy film wideo do edycji, czyli „bezpośrednia edycja filmu wideo”, można dodawać/usuwać/modyfikować elementy, zmieniać kompozycję, styl, kolory, pogodę itp.) lub feature (referencja cech, odniesienie do jego stylu / pracy kamery / kontynuacji nagrania kolejnego ujęcia).
  • keep_original_sound: czy zachować oryginalne audio filmu wideo, opcjonalnie yes (zachowaj) lub no (usuń).
Uwaga: gdy istnieje referencyjny film wideo, generate_audio musi mieć wartość false. Dla filmu z refer_type=base nie można ponownie określić pierwszej / ostatniej klatki.
Przykład CURL edycji istniejącego filmu wideo (zmiana filmu na styl anime) jest następujący:

Referencja wielu obrazów (image_list)

image_list służy do przekazywania obrazów referencyjnych (elementów / scen / stylów itp.). Pola elementów tablicy są następujące:
  • image_url: link do obrazu referencyjnego, nie może być pusty. Wymagania: format .jpg/.jpeg/.png; rozmiar pliku ≤10MB; krótszy bok ≥300px; proporcje obrazu 1:2,5 ~ 2,5:1.
  • type: opcjonalne. Jeśli nie zostanie przekazane, jest używane jako czysty obraz referencyjny; po przekazaniu first_frame / end_frame jest używane odpowiednio jako pierwsza / ostatnia klatka (równoważne start_image_url / end_image_url).
Podczas użycia należy odwoływać się w prompt za pomocą &lt;&lt;<image_1>>>, &lt;&lt;<image_2>>>. Limit liczby: gdy nie ma referencyjnego filmu wideo, liczba obrazów referencyjnych ≤ 7; gdy istnieje referencyjny film wideo, liczba obrazów referencyjnych ≤ 4. Przy przekazywaniu wyłącznie pierwszej / ostatniej klatki można również bezpośrednio użyć start_image_url / end_image_url, ale ostatnia klatka musi być używana razem z pierwszą klatką.
Uwaga: jeśli jednocześnie zostaną przekazane start_image_url / end_image_url oraz image_list, pierwsza / ostatnia klatka zostaną umieszczone przed image_list, co może wpłynąć na powiązanie numeracji &lt;&lt;<image_N>>>. Zaleca się wybór jednej z opcji: gdy potrzebna jest pierwsza / ostatnia klatka, określ type bezpośrednio w image_list, nie mieszaj z start_image_url / end_image_url.
Przykład CURL generowania filmu wideo z referencją wielu obrazów:

Asynchroniczne wywołanie zwrotne

Ponieważ czas generowania przez Kling Videos Generation API jest stosunkowo długi, około 1–2 minut, jeśli API przez długi czas nie odpowiada, żądanie HTTP będzie stale utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API również obsługuje asynchroniczne wywołania zwrotne. Ogólny proces wygląda następująco: gdy klient inicjuje żądanie, dodatkowo określa pole callback_url. Po wysłaniu przez klienta żądania API, API natychmiast zwróci wynik zawierający pole task_id, reprezentujące identyfikator bieżącego zadania. Po ukończeniu zadania wynik wygenerowanego filmu wideo zostanie wysłany w formie POST JSON na callback_url określony przez klienta, gdzie również znajduje się pole task_id, dzięki czemu wyniki zadania można powiązać za pomocą ID. Poniżej, na przykładzie, dowiemy się, jak konkretnie to zrobić. Po pierwsze, wywołanie zwrotne Webhook to usługa, która może odbierać żądania HTTP. Deweloper powinien zastąpić je adresem URL własnego serwera HTTP. Dla wygody demonstracji użyto tutaj publicznej przykładowej strony Webhook https://webhook.site/. Otwarcie tej strony pozwala uzyskać URL Webhook, jak pokazano na ilustracji: Skopiuj ten URL, aby użyć go jako Webhooka; przykładem tutaj jest https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Następnie możemy ustawić pole callback_url na powyższy URL Webhooka i jednocześnie wypełnić odpowiednie parametry. Konkretna zawartość jest pokazana na ilustracji:

Kliknij uruchom, a można zauważyć, że wynik zostanie uzyskany natychmiast, jak poniżej:
Po krótkiej chwili możemy obserwować wynik generowania filmu wideo na https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, jak pokazano na ilustracji: Zawartość jest następująca:
Można zauważyć, że w wyniku znajduje się pole task_id, a pozostałe pola są podobne do opisanych powyżej. Za pomocą tego pola można realizować powiązanie zadań.

Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład:
  • 400 token_mismatched: Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 400 api_not_implemented: Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 401 invalid_token: Brak autoryzacji, nieprawidłowy lub brakujący token autoryzacyjny.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit szybkości.
  • 500 api_error: Wewnętrzny błąd serwera, coś poszło nie tak po stronie serwera.

Przykład odpowiedzi błędu

Podsumowanie

Dzięki temu dokumentowi dowiedziałeś się, jak używać Kling Videos Generation API do generowania wideo za pomocą wprowadzonych podpowiedzi tekstowych oraz referencyjnego obrazu pierwszej klatki. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i używać tego API. W razie jakichkolwiek pytań skontaktuj się w dowolnym momencie z naszym zespołem wsparcia technicznego.

Kling 3.0 Turbo

model="kling-v3-turbo" obsługuje generowanie wideo z tekstu oraz generowanie wideo z obrazu pierwszej klatki, o długości całkowitej od 3 do 15 sekund. mode="std" generuje 720p, a mode="pro" generuje 1080p. Model posiada wbudowany natywny dźwięk i nie udostępnia przełącznika do jego wyłączenia; pomiń generate_audio lub ustaw je na true. Model nie obsługuje ostatniej klatki, obiektów ruchu kamery, niezależnych negatywnych podpowiedzi ani cfg_scale. Opisz bezpośrednio w prompt treści, które mają się pojawić lub których należy unikać.

Wideo wieloujęciowe

kling-v3 i kling-v3-omni obsługują multi_shot=true. shot_type="intelligence" automatycznie tworzy ujęcia na podstawie prompt; shot_type="customize" udostępnia 1–6 ujęć za pomocą multi_prompt, gdzie każda pozycja zawiera index rosnący kolejno od 1, prompt o długości maksymalnie 512 znaków oraz całkowite duration wynoszące co najmniej 1 sekundę. Suma długości wszystkich ujęć musi być równa całkowitemu duration. Dostosowane ujęcia nie używają globalnego prompt. Za wideo wieloujęciowe naliczane są opłaty zgodnie z wybranym modelem, jakością obrazu, konfiguracją audio i całkowitym czasem trwania.