Skip to main content
Ten artykuł 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 obrazów referencyjnych oraz edycję wideo za pośrednictwem jednolitego punktu wejścia /happyhorse/videos i parametru action.

Proces aplikacji

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 ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania z zaproszeniem do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez potrzeby osobnego składania wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz bezpłatny limit, aby móc korzystać z bezpłatnego okresu próbnego; gdy limit będzie niewystarczający, możesz doładować wspólne saldo 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 obrazów referencyjnych, obsługuje happyhorse-1.0-r2v i happyhorse-1.1-r2v, należy przekazać prompt oraz 1–9 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.
Każda akcja domyślnie używa 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 zwracany wynik jest następujący:
Opis pól:
  • success: czy bieżące żądanie zakończyło się powodzeniem.
  • 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, dostępne wartości to pending / succeeded / error.
    • duration: rozliczany czas trwania wideo, w sekundach; dla video_edit jest to łączny czas trwania wideo wejściowego i wyjściowego.
    • resolution: rozdzielczość wyjściowa.
    • ratio: proporcje szerokości do wysokości wyjścia.
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ściowe proporcje szerokości do wysokości będą w miarę możliwości zgodne z obrazem pierwszej klatki, dlatego ta akcja nie wymaga przekazania ratio.

Generowanie wideo z obrazów referencyjnych

Podczas używania reference_to_video, image_urls może przyjąć 1–9 obrazów referencyjnych. W promptcie można używać character1, character2 itd., aby odwoływać się do obrazów w odpowiedniej kolejności.

Edycja 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 przyjmować wartość auto lub 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, wtedy API natychmiast zwróci task_id, a po zakoń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 używania callbacku, możesz również przekazać "async": true, a następnie sprawdzić wynik zadania za pomocą HappyHorse Tasks API.

Informacje o rozliczeniach

HappyHorse rozlicza według liczby sekund wyjściowego wideo i rozdzielczości:
  • 720P: już od około $0.105 / sekundę.
  • 1080P: już od około $0.18 / sekundę.
  • video_edit: rozliczane według łącznego czasu trwania wejściowego i wyjściowego wideo, a rzeczywisty czas rozliczeniowy jest określany na podstawie statystyk po zakończeniu zadania.
Nieudane zadania nie są rozliczane ani nie wykorzystują darmowego limitu.

Obsługa błędów

Gdy wystąpi problem z żądaniem, API zwróci odpowiedni kod błędu i opis, najczęstsze 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 przez moderację treści.
  • 429: żądania są zbyt częste, uruchomiono ograniczenie szybkości, spróbuj ponownie później.
  • 500: wewnętrzny błąd serwera lub niepowodzenie generowania.