> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instrukcja integracji z API generowania filmów Kling > Kling video generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/3b921a16-a411-4557-8335-53f21d3f9e46). Po wejściu na stronę kliknij przycisk „Acquire”, jak pokazano na poniższym obrazku: ![](https://cdn.xhuoapi.ai/q6ytrc.png) 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](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z). * `video_list`: lista filmów referencyjnych dostępnych przez URL, stosowana tylko w modelu `kling-video-o1`. Szczegóły w [dokumentacji oficjalnej](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z). * `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: ```json theme={null} { "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: ```shell theme={null} 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](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels). 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: ```python theme={null} 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: ```json theme={null} { "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/](https://webhook.site/), gdzie po wejściu uzyskujemy unikalny URL webhooka, jak pokazano na obrazku: ![](https://cdn.xhuoapi.ai/tbcnai.png) 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: ![](https://cdn.xhuoapi.ai/zv5u2q.png) Zawartość: ```json theme={null} { "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 ```json theme={null} { "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.