Dokumentacja integracji API generacji filmów Kling

W tym artykule przedstawimy dokumentację integracji API generacji filmów Kling, które umożliwia generowanie oficjalnych filmów Kling poprzez wprowadzenie niestandardowych parametrów.

Proces aplikacji

Aby korzystać z API generacji filmów Kling, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój token API, który należy zachować na przyszłość.

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; w przypadku niewystarczającego limitu możesz doładować saldo ogólne w konsoli.

📘 Pełna dokumentacja: API generacji filmów Kling →

Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, czyli wprowadzeniem 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, które głównie zawiera trzy rodzaje działań: generowanie wideo z tekstu (text2video), generowanie wideo z obrazu (image2video), rozszerzenie 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 generujący 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 kling-v3 i kling-v3-omni, a także jest niekompatybilny z camera_control (kontrola kamery).
action: działanie w zadaniu generowania wideo, głównie obejmujące trzy działania: generowanie wideo z tekstu (text2video), generowanie wideo z obrazu (image2video), rozszerzenie wideo (extend).
start_image_url: przy wyborze działania generowania wideo z obrazu image2video konieczne jest przesłanie linku do referencyjnego obrazu.
end_image_url: opcjonalne przy generowaniu wideo z obrazu, określa ostatnią klatkę.
duration: czas trwania 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: intensywność związku, zakres [0,1], im większa wartość, tym bardziej zgodna z podanym słowem kluczowym.
camera_control: opcjonalne, parametry kontrolujące ruch kamery, obsługuje predefiniowane typy/proste oraz konfiguracje horizontal, vertical, pan, tilt, roll, zoom itp.
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:

{
  "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, stan zadania generowania wideo w danym momencie.
task_id, ID zadania generowania wideo w danym momencie.
video_id, ID wideo w danym momencie.
video_url, link do wideo w danym momencie.
duration, czas trwania wideo w danym momencie.
state, stan zadania generowania wideo w danym momencie.

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:

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, przed wywołaniem proszę upewnić się, że aktualna kombinacja model / mode / duration obsługuje wymagane funkcje, w przeciwnym razie zwróci błąd model/mode/duration(...) is not supported with image_tail itp.

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 podstawowego użycia opisanego powyżej.

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:

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ącym marmurowym 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 również 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 <<<image_1>>>, <<<video_1>>> (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łane są 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 Elementów Kling nie jest izolowane dla najemców, przed udostępnieniem API zarządzania Elementami z izolacją najemców, proszę użyć image_list do przesłania głównego obrazu referencyjnego.

Żą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. video_list służy do przekazywania referencyjnych filmów, jest to najczęściej używany scenariusz w tej funkcjonalności, elementy tablicy mają następujące pola:

video_url: link do referencyjnego filmu, nie może być pusty. Maksymalnie 1 film MP4/MOV, rozmiar pliku ≤200MB, liczba klatek na sekundę 24–60fps. kling-o1 wymaga długości 3–10 sekund, szerokości i wysokości od 700 do 2160px; kling-v3-omni wymaga długości 3–15,5 sekundy, szerokości i wysokości od 700 do 4553px, całkowite piksele ≤8,294,400, proporcja szerokości do wysokości 0,4–2.
refer_type: typ referencji, opcjonalnie base (domyślnie, podstawowy film do edycji, czyli “bezpośrednia edycja filmu”, można dodawać/usuwać/modyfikować elementy, zmieniać kompozycję, styl, kolor, pogodę itp.) lub feature (referencja 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 referencyjny film, generate_audio musi być ustawione na false. Filmy z refer_type=base nie mogą mieć określonej pierwszej/ostatniej klatki.

Przykład CURL do edycji istniejącego filmu (zmiana stylu na anime) wygląda następująco:

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ń <<<video_1>>> 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"
    }
  ]
}'

Referencje wieloobrazowe (`image_list`)

image_list służy do przekazywania referencyjnych obrazów (elementy / sceny / styl itp.), elementy tablicy mają następujące pola:

image_url: link do referencyjnego obrazu, nie może być pusty. Wymagania: format .jpg/.jpeg/.png; rozmiar pliku ≤10MB; najkrótszy bok ≥300px; proporcja szerokości do wysokości 1:2.5 ~ 2.5:1.
type: opcjonalnie. Jeśli nie jest podany, traktowany jako czysty obraz referencyjny; podanie first_frame / end_frame traktowane jest odpowiednio jako pierwsza/ostatnia klatka (równoważne start_image_url / end_image_url).

Podczas użycia należy w prompt odwołać się do <<<image_1>>>, <<<image_2>>>. Ograniczenie liczby: gdy nie ma referencyjnego filmu, obrazy referencyjne ≤ 7; gdy istnieje referencyjny film, obrazy referencyjne ≤ 4. Można również bezpośrednio użyć start_image_url / end_image_url, gdy przekazywane są tylko pierwsza/ostatnia klatka, 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 znajdować się przed image_list, co może wpłynąć na odpowiedniość numerów <<<image_N>>>. Zaleca się wybór jednej opcji: gdy 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 referencjami wieloobrazowymi:

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 <<<image_1>>> stanie w scenie z <<<image_2>>>, 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 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 tym również 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, 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/, otwierając tę stronę można uzyskać URL Webhook, jak pokazano na obrazku:

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:

Zawartość jest następująca:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Można zauważyć, że w wyniku znajduje się pole task_id, a pozostałe pola są podobne do wcześniej opisanych, dzięki temu pole można wykorzystać do powiązania zadań.

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 autoryzacji.
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

{
  "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, aby generować wideo za pomocą 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.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Proxy

Advanced

Coding

Dokumentacja integracji API generacji filmów Kling

Proces aplikacji

Podstawowe użycie

Macierz możliwości modeli

Funkcje rozszerzonego wideo

Omni wszechstronny odniesienie (edycja wideo / wideo referencyjne / wiele obrazów referencyjnych)

Referencje wieloobrazowe (`image_list`)

Asynchroniczne powiadomienia

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski

​Proces aplikacji

​Podstawowe użycie

​Macierz możliwości modeli

​Funkcje rozszerzonego wideo

​Omni wszechstronny odniesienie (edycja wideo / wideo referencyjne / wiele obrazów referencyjnych)

​Wideo referencyjne i edycja wideo (video_list)

​Referencje wieloobrazowe (image_list)

​Asynchroniczne powiadomienia

​Obsługa błędów

​Przykład odpowiedzi błędu

​Wnioski

Proces aplikacji

Podstawowe użycie

Macierz możliwości modeli

Funkcje rozszerzonego wideo

Omni wszechstronny odniesienie (edycja wideo / wideo referencyjne / wiele obrazów referencyjnych)

Wideo referencyjne i edycja wideo (`video_list`)

Referencje wieloobrazowe (`image_list`)

Asynchroniczne powiadomienia

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski