Przejdź do głównej treści
Ten dokument przedstawia sposób integracji z HappyHorse Videos API. Ten interfejs obsługuje generowanie wideo z tekstu, generowanie wideo z obrazu pierwszej klatki, generowanie wideo z obrazu referencyjnego oraz edycję wideo za pośrednictwem jednolitego punktu wejścia /happyhorse/videos i parametru action.

Proces składania wniosku

Aby korzystać z HappyHorse Videos 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(-a) ani zarejestrowany(-a), zostaniesz automatycznie przekierowany(-a) na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się. Po zakończeniu automatycznie powrócisz na bieżącą stronę. Jeden API Token pozwala wywoływać wszystkie usługi platformy, bez konieczności składania osobnego wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz darmowy limit, który pozwala na bezpłatne testowanie; gdy limit jest niewystarczający, możesz doładować saldo ogólne w konsoli.
📘 Pełna dokumentacja: HappyHorse Videos API →

Typy operacji

action określa tryb generowania dla bieżącego żądania:
  • generate: generowanie wideo z tekstu, domyślna akcja, obsługuje happyhorse-1.0-t2v i happyhorse-1.1-t2v, należy przekazać prompt.
  • image_to_video: generowanie wideo z obrazu pierwszej klatki, obsługuje happyhorse-1.0-i2v i happyhorse-1.1-i2v, należy przekazać image_url.
  • reference_to_video: generowanie wideo z obrazu referencyjnego, obsługuje happyhorse-1.0-r2v i happyhorse-1.1-r2v, należy przekazać prompt oraz 1–9 obrazów image_urls.
  • video_edit: edycja wideo, obsługuje happyhorse-1.0-video-edit, należy przekazać prompt i video_url, można dodatkowo przekazać 0–5 obrazów referencyjnych image_urls.
Poszczególne akcje domyślnie używają modelu 1.1; video_edit obecnie ma tylko happyhorse-1.0-video-edit.

Podstawowe użycie

Generowanie wideo z tekstu wymaga jedynie podania prompt; można również określić parametry takie jak resolution, ratio, duration itd.:
Przykładowy wynik zwracany jest poniżej:
Opis pól:
  • success: czy bieżące żądanie zakończyło się pomyślnie.
  • task_id: ID zadania po stronie Ace Data Cloud, może być używane do sprawdzania statusu zadania.
  • trace_id: ID śledzenia bieżącego żądania, używane do rozwiązywania problemów.
  • data: lista wyników wideo.
    • id: ID zadania po stronie HappyHorse.
    • video_url: adres linku CDN wygenerowanego wideo.
    • state: status zadania, opcje to pending / succeeded / error.
    • duration: rozliczany czas trwania wideo w sekundach; dla video_edit jest to suma czasu trwania wejściowego i wyjściowego wideo.
    • resolution: rozdzielczość wyjściowa.
    • ratio: wyjściowy współczynnik proporcji.
Odpowiedni kod CURL jest następujący:
Odpowiedni kod Python jest następujący:

Generowanie wideo z obrazu pierwszej klatki

Podczas używania image_to_video, image_url będzie używany jako pierwsza klatka wideo. Wyjściowy współczynnik proporcji będzie w miarę możliwości podążał za obrazem pierwszej klatki, dlatego ta akcja nie wymaga przekazania ratio.

Generowanie wideo z obrazu referencyjnego

Podczas używania reference_to_video, do image_urls można przekazać 1–9 obrazów referencyjnych. W tekście polecenia można odwoływać się do obrazów w odpowiedniej kolejności za pomocą character1, character2 itd.

Edycja wideo

Czas trwania i format kadru wyjściowego video_edit dziedziczą po źródłowym wideo; przekazanie duration lub ratio ich nie zmieni; format kadru wideo generowanego z obrazu również dziedziczy po obrazie źródłowym. Koszt edycji jest obliczany na podstawie sumy czasu trwania wejściowego i wyjściowego wideo. Podczas używania video_edit należy przekazać edytowane wideo video_url oraz intencję edycji prompt. Opcjonalne image_urls będą używane jako obrazy referencyjne, na przykład do zmiany stroju, transferu stylu lub lokalnej zamiany. audio_setting może opcjonalnie mieć wartość auto albo origin, gdzie origin oznacza zachowanie oryginalnego dźwięku wideo.

Asynchroniczne wywołanie zwrotne

Generowanie wideo wymaga pewnego czasu przetwarzania. Jeśli nie chcesz utrzymywać długiego połączenia w oczekiwaniu, możesz przekazać callback_url; w takim przypadku API natychmiast zwróci task_id, a po ukończeniu zadania wyśle końcowy wynik metodą POST na ten adres:
Natychmiast zwrócony wynik jest następujący:
Jeśli chcesz tylko odpytywać, bez potrzeby wywołania zwrotnego, możesz również przekazać "async": true, a następnie sprawdzić wynik zadania za pośrednictwem HappyHorse Tasks API.

Informacje o rozliczeniach

HappyHorse nalicza opłaty według liczby sekund wyjściowego wideo i rozdzielczości:
  • 720P: od około $0.105 / sekundę.
  • 1080P: od około $0.18 / sekundę.
  • video_edit: opłata jest naliczana łącznie za czas trwania wejściowego i wyjściowego wideo; rzeczywisty rozliczany czas trwania jest oparty na statystykach po ukończeniu zadania.
Nieudane zadania nie są płatne ani nie wykorzystują bezpłatnego limitu.

Obsługa błędów

Gdy wystąpi problem z żądaniem, API zwróci odpowiedni kod błędu i opis; typowe są następujące:
  • 400: parametry żądania są nieprawidłowe, na przykład action nie pasuje do modelu, brakuje prompt / image_url / video_url lub duration wykracza poza zakres 3–15 sekund.
  • 401: uwierzytelnianie nie powiodło się, token jest nieprawidłowy lub nie pasuje do API.
  • 403: niewystarczające saldo lub monit został odrzucony z powodu moderacji treści.
  • 429: żądania są zbyt częste, uruchomiono ograniczenie liczby żądań, spróbuj ponownie później.
  • 500: wewnętrzny błąd serwera lub niepowodzenie generowania.