Skip to main content
W tym artykule przedstawimy sposób integracji z Kling Motion Generation API, które pozwala na generowanie oficjalnych filmów Kling poprzez wprowadzenie niestandardowych parametrów.

​
Proces aplikacji

Aby korzystać z Kling Motion Generation API, najpierw przejdź do Ace Data Cloud Console, 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 przetestować; gdy limit się wyczerpie, możesz doładować saldo ogólne w konsoli.
📘 Pełna dokumentacja: Kling Motion Generation API →

​
Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, czyli wprowadzeniem słowa kluczowego prompt, adresu URL obrazu image_url oraz linku do wideo video_url, aby uzyskać przetworzony wynik. Następnie musimy również wprowadzić model mode, który obecnie obejmuje głównie modele std i pro, szczegóły są następujące:

Możemy zobaczyć, że ustawiliśmy nagłówki żądania, w tym:
  • accept: jakiego formatu odpowiedzi oczekujemy, 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 ustawiliśmy ciało żądania, w tym:
  • image_url: URL referencyjnego obrazu wyglądu postaci. Obsługuje JPG/JPEG/PNG, plik ≤50MB, szerokość i wysokość ≥300px, proporcje 1:2.5～2.5:1; postać powinna być wyraźnie widoczna w górnej części ciała lub w całej postaci oraz głowie.
  • video_url: URL referencyjnego wideo akcji. Obsługuje MP4/MOV, plik ≤100MB, szerokość i wysokość od 340 do 3850px, co najmniej 3 sekundy; przy character_orientation=image maksymalnie 10 sekund, przy character_orientation=video maksymalnie 30 sekund. Zaleca się użycie wideo z postacią zawsze w kadrze w jednym ujęciu.
  • mode: tryb generowania wideo, głównie standardowy tryb std i tryb superszybki pro.
  • keep_original_sound: możliwość wyboru, czy zachować oryginalny dźwięk wideo, wartości enum: yes, no.
  • character_orientation: orientacja postaci w generowanym wideo, można wybrać zgodnie z obrazem lub wideo, wartości enum: image, video.
  • 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 za pomocą odpowiedniego interfejsu zapytań o zadania.
Po dokonaniu wyboru, można zauważyć, że po prawej stronie wygenerowano odpowiedni kod, jak pokazano na rysunku:

Klikając przycisk „Try”, można przeprowadzić test, jak pokazano na powyższym obrazku, uzyskując następujący wynik:
Zwrócony wynik zawiera wiele pól, które są opisane poniżej:
  • success, status zadania generowania wideo w tym momencie.
  • task_id, ID zadania generowania wideo w tym momencie.
  • video_id, ID wideo generowanego w tym momencie.
  • video_url, link do wideo generowanego w tym momencie.
  • duration, długość wideo generowanego w tym momencie.
  • state, status zadania generowania wideo w tym momencie.
Możemy zobaczyć, że uzyskaliśmy satysfakcjonujące informacje o wideo, wystarczy, że na podstawie adresu URL wideo w data uzyskamy wygenerowane wideo Kling. Dodatkowo, jeśli chcesz wygenerować odpowiedni kod do integracji, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:

​
Asynchroniczne wywołanie zwrotne

Ponieważ czas generowania przez Kling Motion Generation API 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 wywołań zwrotnych. Cały proces wygląda następująco: klient inicjuje żądanie, dodatkowo określając pole callback_url, po złożeniu żądania API natychmiast zwraca wynik, zawierający pole task_id, które reprezentuje aktualne ID zadania. Po zakończeniu zadania wynik generowania wideo zostanie wysłany do określonego przez klienta callback_url w formie POST JSON, w tym również pole task_id, dzięki czemu wyniki zadania można powiązać za pomocą ID. Poniżej przedstawiamy przykład, aby zrozumieć, jak to działa. Najpierw, wywołanie zwrotne Webhook to usługa, która może odbierać żądania HTTP, deweloperzy powinni zastąpić to URL swojego serwera HTTP. W celu wygodnej demonstracji użyjemy publicznej strony przykładowej Webhook https://webhook.site/, otwierając tę stronę, otrzymasz URL Webhook, jak pokazano na rysunku: 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 wprowadzić odpowiednie parametry, szczegóły jak pokazano na rysunku:

Klikając „Uruchom”, można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej:
Po chwili możemy na https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 zobaczyć wynik generowania wideo, jak pokazano na rysunku: Treść jest następująca:
Można zauważyć, że w wynikach znajduje się pole task_id, a pozostałe pola są podobne do powyższych, dzięki czemu można powiązać zadania.

​
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: 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 szybkości.
  • 500 api_error: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

​
Przykład odpowiedzi błędu

​
Wnioski

Dzięki temu dokumentowi zrozumieliście, jak używać API Kling Motion Generation do realizacji funkcji kontroli ruchu oficjalnego Klinga. Mamy nadzieję, że ten dokument pomoże Wam lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, prosimy o kontakt z naszym zespołem wsparcia technicznego.