> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Dokumentacja integracji API generacji filmów Kling > Kling video generation API guide - Ace Data Cloud W tym artykule przedstawimy dokumentację integracji API generacji filmów Kling, które umożliwia generowanie oficjalnych filmów Kling za pomocą wprowadzonych parametrów. ## Proces aplikacji Aby korzystać z API generacji filmów Kling, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. **Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Przy pierwszym wniosku otrzymasz darmowy limit, aby móc skorzystać z usługi; gdy limit się wyczerpie, możesz doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [API generacji filmów Kling →](https://platform.acedata.cloud/documents/kling-videos) ## Podstawowe użycie Najpierw zapoznaj się z podstawowym sposobem użycia, polegającym na wprowadzeniu słowa kluczowego `prompt`, działania `action`, linku do referencyjnego obrazu `start_image_url` oraz modelu `model`, aby uzyskać przetworzony wynik. Najpierw musisz przekazać pole `action`, którego wartość to `text2video`. Obejmuje ono trzy główne działania: generowanie wideo z tekstu (`text2video`), generowanie wideo z obrazu (`image2video`), rozszerzanie wideo (`extend`). Następnie musimy również wprowadzić model `model`, który obecnie 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`, szczegóły są następujące:

Możemy zobaczyć, że ustawiliśmy nagłówki żądania, w tym: * `accept`: format odpowiedzi, który chcemy otrzymać, tutaj wpisujemy `application/json`, czyli format JSON. * `authorization`: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z rozwijanej listy. Dodatkowo ustawiono ciało żądania, w tym: * `model`: model do generowania wideo, głównie `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, opcjonalne wartości to standardowy tryb `std`, tryb superszybki `pro` oraz natywny tryb 4K `4k`. Tryb `4k` obsługuje tylko modele `kling-v3` i `kling-v3-omni`, a także jest niekompatybilny z `camera_control` (kontrola kamery). * `action`: działanie związane z generowaniem wideo, głównie obejmujące trzy działania: generowanie wideo z tekstu (`text2video`), generowanie wideo z obrazu (`image2video`), rozszerzanie wideo (`extend`). * `start_image_url`: przy wyborze działania generowania wideo z obrazu `image2video` należy przesłać link do referencyjnego obrazu. * `end_image_url`: opcjonalne przy generowaniu wideo z obrazu, określa ostatnią klatkę. * `duration`: długość wideo, w sekundach. `kling-v3` i `kling-v3-omni` obsługują długości całkowite od 3 do 15 sekund; `kling-o1` obsługuje tylko 5 sekund; inne modele obsługują 5 lub 10 sekund. * `generate_audio`: czy synchronizować generowanie dźwięku, opcjonalne, wartość logiczna. Obsługuje `kling-v3`, `kling-v3-omni` oraz `kling-v2-6` (tylko w trybie 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 związku, zakres \[0,1], im większa, tym bardziej zgodna z podanym słowem kluczowym. * `camera_control`: opcjonalne, parametry kontrolujące ruch kamery, obsługuje predefiniowane typy/simple oraz konfiguracje horizontal, vertical, pan, tilt, roll, zoom. * `negative_prompt`: opcjonalne, słowa kluczowe, których nie chcemy, maksymalnie 200 znaków. * `image_list`: lista referencyjnych obrazów Omni, odpowiednia dla modeli `kling-o1` i `kling-v3-omni`, sposób użycia opisany poniżej w sekcji „Omni pełne odniesienie”. * `video_list`: lista referencyjnych filmów Omni (obsługuje edycję wideo), odpowiednia dla modeli `kling-o1` i `kling-v3-omni`, sposób użycia opisany poniżej w sekcji „Omni pełne odniesienie”. * `prompt`: słowo kluczowe. * `callback_url`: URL, na który mają być zwracane wyniki. * `async`: opcjonalne, ustawione na `true`, interfejs natychmiast zwraca `task_id`, nie ma potrzeby podawania `callback_url`, a następnie można uzyskać wyniki, korzystając z odpowiedniego interfejsu zapytań o zadania. Po dokonaniu wyboru można zauważyć, że po prawej stronie wygenerowano odpowiedni kod, jak pokazano na obrazku:

Kliknij przycisk „Try”, aby przeprowadzić test, jak pokazano na powyższym obrazku, otrzymujemy następujący wynik: ```json theme={null} { "success": true, "video_id": "900798310464749610", "video_url": "https://platform2.cdn.acedata.cloud/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5.mp4", "duration": "5.041", "state": "succeed", "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5" } ``` Zwrócone wyniki zawierają wiele pól, które są opisane poniżej: * `success`, status zadania generowania wideo. * `task_id`, ID zadania generowania wideo. * `video_id`, ID wideo generowanego w ramach zadania. * `video_url`, link do wideo generowanego w ramach zadania. * `duration`, długość wideo generowanego w ramach zadania. * `state`, status zadania generowania wideo. Możemy zobaczyć, że otrzymaliśmy zadowalające informacje o wideo, wystarczy, że na podstawie adresu linku wideo w `data` uzyskamy wygenerowane wideo Kling. Dodatkowo, jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-v3", "prompt": "Biały ceramiczny kubek do kawy na błyszczącej marmurowej blacie z porannym światłem z okna. Kamera powoli obraca się o 360 stopni wokół kubka, zatrzymując się na chwilę przy uchwycie." }' ``` ## Macierz możliwości modeli Różne modele mają różne wsparcie dla parametrów. Poniższa macierz została opracowana na podstawie [oficjalnej dokumentacji modeli wideo Kling](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels), przed wywołaniem proszę sprawdzić, czy aktualna kombinacja `model` / `mode` / `duration` obsługuje wymagane funkcje, w przeciwnym razie serwer zwróci błędy, takie jak `model/mode/duration(...) is not supported with image_tail`. | Model | Mode | `end_image_url` (klatka końcowa) | `generate_audio` (dźwięk) | `camera_control` (sterowanie kamerą) | Uwagi | | ------------------- | -------------- | -------------------------------- | ------------------------- | ------------------------------------ | ------------------------------------------------------ | | `kling-v1` | std / pro | ✅ tylko `duration=5` | ❌ | ✅ tylko `duration=5` | `extend` nie wspiera `negative_prompt` i `cfg_scale` | | `kling-v1-6` | std | ❌ | ❌ | ❌ | Wiele obrazów wideo, `extend` dostępne w trybie pełnym | | `kling-v1-6` | pro | ✅ | ❌ | ❌ | | | `kling-v2-master` | — | ❌ | ❌ | ❌ | Tryb pojedynczy, tylko `duration=5/10` | | `kling-v2-1-master` | — | ❌ | ❌ | ❌ | Tryb pojedynczy, tylko `duration=5/10` | | `kling-v2-5-turbo` | std | ❌ | ❌ | ❌ | | | `kling-v2-5-turbo` | pro | ✅ | ❌ | ❌ | | | `kling-v2-6` | std | ❌ | ❌ | ❌ | | | `kling-v2-6` | pro | ✅ | ✅ | ❌ | Jedyny model nie v3, który jednocześnie wspiera dźwięk | | `kling-v3` | std / pro | ✅ | ✅ | ✅ | Zakres `duration` 3–15 sekund | | `kling-v3` | 4k | ✅ | ✅ | ❌ | Tryb 4K niekompatybilny z kontrolą kamery | | `kling-v3-omni` | std / pro / 4k | ✅ | ✅ | ❌ | | | `kling-o1` | std / pro | ✅ | ❌ | ❌ | Wspiera tylko `duration=5` | Uwagi: * `mode=4k` wspierają tylko `kling-v3` i `kling-v3-omni`; jest to również wykluczone z `camera_control` (sterowanie kamerą). * `end_image_url` może być używane tylko w połączeniu z `start_image_url` podczas `action=image2video`. Przesłanie tylko `end_image_url` (bez `start_image_url`) zostanie odrzucone. * `kling-v3` / `kling-v3-omni` akceptują dowolny całkowity `duration` od 3 do 15 sekund; `kling-o1` akceptuje tylko 5; pozostałe modele akceptują tylko 5 lub 10. * `generate_audio` domyślnie `false`. Tylko `kling-v3`, `kling-v3-omni` i `kling-v2-6` (tryb pro) wspierają. ## Funkcje rozszerzonego wideo Jeśli chcesz kontynuować generowanie już wygenerowanego wideo Kling, możesz ustawić parametr `action` na `extend` i wprowadzić ID wideo, które chcesz kontynuować. ID wideo można uzyskać na podstawie podstawowego użycia, jak pokazano na poniższym obrazku:

W tym momencie można zobaczyć, że ID wideo to: ``` "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c" ``` > Uwaga, tutaj `video_id` w wideo to ID wygenerowanego wideo. Jeśli nie wiesz, jak wygenerować wideo, możesz odwołać się do powyższego opisu podstawowego użycia. Następnie musimy wypełnić kolejne kroki, aby rozszerzyć podpowiedzi do dostosowania generowanego wideo, można określić następujące treści: * `model`: model generujący wideo, głównie `kling-v1`, `kling-v1-5` i `kling-v1-6`. * `mode`: tryb generowania wideo, możliwe wartości to standardowy tryb `std`, tryb superszybki `pro` i natywny tryb 4K `4k` (tylko `kling-v3` i `kling-v3-omni` wspierają, niekompatybilny z kontrolą kamery). * `duration`: czas trwania zadania generowania wideo, głównie 5s i 10s. * `start_image_url`: gdy wybierasz działanie generowania wideo z obrazu `image2video`, musisz przesłać link do referencyjnego obrazu klatki początkowej. * `prompt`: podpowiedź. Przykład wypełnienia:

Po wypełnieniu automatycznie generuje kod jak poniżej:

Odpowiedni kod Python: ```python theme={null} import requests url = "https://api.acedata.cloud/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": "Biały ceramiczny kubek do kawy na błyszczącej marmurowej blacie z porannym światłem z okna. Kamera powoli obraca się o 360 stopni wokół kubka, zatrzymując się na chwilę przy uchwycie.", "duration": 10 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Po kliknięciu uruchomienia można zauważyć, że otrzymany wynik jest zgodny z powyższym, co realizuje funkcję rozszerzenia wideo. ## Omni wszechstronny odniesienie (edycja wideo / wideo referencyjne / wiele obrazów referencyjnych) `kling-o1` i `kling-v3-omni` to dwa niezależne modele, które wspierają zdolność „wszechstronnego odniesienia”. Na podstawie generowania wideo z tekstu (`action=text2video`) można dodatkowo przesłać obrazy referencyjne lub wideo referencyjne, aby zrealizować **wiele obrazów referencyjnych, wideo referencyjne oraz bezpośrednią edycję istniejącego wideo**. **Podstawowe ustalenie**: Materiały referencyjne muszą być cytowane w `prompt` w formie `<<>>`, `<<>>` (numeracja zaczyna się od 1) w odniesieniu do odpowiednich pozycji w `image_list` / `video_list`, aby model mógł zastosować te odniesienia. Jeśli przesłano tylko materiały bez ich cytowania w podpowiedzi, materiały zostaną zignorowane. > Uwaga bezpieczeństwa: obecne API nie udostępnia `element_list`. ID z biblioteki Kling Element Library należy do przestrzeni nazw konta dostawcy, przed udostępnieniem API zarządzania elementami z izolacją najemców, klienci powinni przesyłać materiały referencyjne za pomocą `image_list`. Żądania Omni nie wspierają `negative_prompt`, `cfg_scale` ani `camera_control`, a także nie mogą używać `mode=4k`. W przypadku zawierania wideo referencyjnego, `generate_audio` musi być ustawione na `false`. ### Przykładowe wideo i edycja wideo (`video_list`) `video_list` służy do przekazywania przykładowych wideo, jest to najczęściej używany scenariusz w tej funkcjonalności, elementy tablicy mają następujące pola: * `video_url`: link do przykładowego wideo, nie może być pusty. Wymagania: format MP4/MOV; rozdzielczość 720px–2160px; czas trwania 3–10 sekund; liczba klatek 24–60fps; rozmiar pliku ≤200MB; maksymalnie 1 wideo. * `refer_type`: typ odniesienia, opcjonalnie `base` (domyślnie, **podstawowe wideo do edycji**, czyli "bezpośrednia edycja wideo", można dodawać/usuwać/modyfikować elementy, zmieniać kompozycję, styl, kolor, pogodę itp.) lub `feature` (**odniesienie do cech**, odniesienie do stylu / ruchu kamery / kontynuacji następnej sceny). * `keep_original_sound`: czy zachować oryginalny dźwięk wideo, opcjonalnie `yes` (zachować) lub `no` (usunąć). > Uwaga: gdy istnieje przykładowe wideo, `generate_audio` musi być ustawione na `false`. Wideo z `refer_type=base` nie może mieć określonej pierwszej/ostatniej klatki. Przykład CURL do edycji istniejącego wideo (zmiana wideo na styl anime) wygląda następująco: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Zmień <<>> na filmowy styl anime, zachowując oryginalny ruch i kompozycję", "video_list": [ { "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4", "refer_type": "base", "keep_original_sound": "no" } ] }' ``` ### Przykłady wielu obrazów (`image_list`) `image_list` służy do przekazywania przykładowych obrazów (elementy / sceny / styl itp.), elementy tablicy mają następujące pola: * `image_url`: link do przykładowego obrazu, nie może być pusty. Wymagania: format .jpg/.jpeg/.png; rozmiar pliku ≤10MB; najkrótszy bok ≥300px; proporcje 1:2.5 \~ 2.5:1. * `type`: opcjonalnie. Jeśli nie jest przekazywane, traktowane jako czysty obraz referencyjny; przekazując `first_frame` / `end_frame`, będzie traktowane jako pierwsza/ostatnia klatka (równoważne `start_image_url` / `end_image_url`). Podczas użycia należy w `prompt` odwołać się do `<<>>`, `<<>>`. Ograniczenie liczby: gdy nie ma przykładowego wideo, obrazy referencyjne ≤ 7; gdy istnieje przykładowe wideo, obrazy referencyjne ≤ 4. 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 przekazywane są `start_image_url` / `end_image_url` oraz `image_list`, pierwsza/ostatnia klatka będzie miała pierwszeństwo przed `image_list`, co może wpłynąć na powiązania numerów `<<>>`. Zaleca się wybór jednej opcji: jeśli potrzebne są pierwsza/ostatnia klatka, należy bezpośrednio w `image_list` użyć `type`, nie mieszając z `start_image_url` / `end_image_url`. Przykład CURL do generowania wideo z wielu obrazów: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Niech postać z <<>> stanie w scenie z <<>>, filmowe oświetlenie", "image_list": [ { "image_url": "https://cdn.acedata.cloud/subject.png" }, { "image_url": "https://cdn.acedata.cloud/scene.png" } ] }' ``` ## Asynchroniczne powiadomienia Ponieważ czas generacji wideo przez API Kling Videos jest stosunkowo długi, wynosi około 1-2 minut, jeśli API nie odpowiada przez dłuższy czas, żądanie HTTP będzie utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API oferuje również wsparcie dla asynchronicznych powiadomień. Cały proces wygląda następująco: klient inicjuje żądanie, dodatkowo określając pole `callback_url`, po wysłaniu żądania API natychmiast zwraca wynik, zawierający pole `task_id`, które reprezentuje aktualny identyfikator zadania. Po zakończeniu zadania, wynik generacji wideo zostanie wysłany do określonego przez klienta `callback_url` w formie POST JSON, w którym również znajduje się pole `task_id`, co pozwala na powiązanie wyniku zadania z jego identyfikatorem. Poniżej przedstawiamy przykład, aby zrozumieć, jak to działa. Najpierw, powiadomienia Webhook to usługa, która może odbierać żądania HTTP, deweloperzy powinni zastąpić to URL swojego serwera HTTP. W tym celu, dla wygody demonstracji, używamy publicznej strony przykładowej Webhook [https://webhook.site/](https://webhook.site/), otwierając tę stronę można uzyskać URL Webhook, jak pokazano na obrazku: ![](https://cdn.acedata.cloud/tbcnai.png) Skopiuj ten URL, aby użyć go jako Webhook, przykładowy URL to `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`. Następnie możemy ustawić pole `callback_url` na powyższy URL Webhook, a także wypełnić odpowiednie parametry, szczegóły jak na obrazku:

Klikając uruchom, można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej: ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` Po chwili możemy na `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3` zobaczyć wynik generacji wideo, jak pokazano na obrazku: ![](https://cdn.acedata.cloud/zv5u2q.png) Zawartość wygląda następująco: ```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" } ``` Można zauważyć, że wynik zawiera pole `task_id`, a pozostałe pola są podobne do wcześniej, dzięki czemu można powiązać zadanie z jego identyfikatorem. ## Obsługa błędów Podczas wywoływania API, jeśli wystąpią błędy, API zwróci odpowiedni kod błędu i informacje. Na przykład: * `400 token_mismatched`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. * `400 api_not_implemented`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. * `401 invalid_token`: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny. * `429 too_many_requests`: Zbyt wiele żądań, przekroczono limit. * `500 api_error`: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze. ### Przykład odpowiedzi błędu ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "pobieranie nie powiodło się" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Wnioski Dzięki temu dokumentowi zrozumiałeś, jak korzystać z API Kling Videos Generation, które umożliwia generowanie wideo na podstawie wprowadzonych słów kluczowych oraz obrazu referencyjnego pierwszej klatki. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, prosimy o kontakt z naszym zespołem wsparcia technicznego.