Przejdź do głównej treści
Ten artykuł przedstawi instrukcję integracji Gemini Videos Generation API, które może generować filmy Google Gemini (omni-flash) poprzez wprowadzenie tekstowego promptu (oraz opcjonalnych obrazów referencyjnych).

Proces aplikacji

Aby korzystać z Gemini Videos Generation API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go do późniejszego użycia. 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 powró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 uzyskaniu tokenu otrzymasz darmowy limit, aby bezpłatnie wypróbować usługę; gdy limit jest niewystarczający, możesz doładować wspólne saldo w konsoli.
📘 Pełna dokumentacja: Gemini Videos Generation API →

Podstawowe użycie

Najpierw zapoznajmy się z podstawowym sposobem użycia: wprowadź prompt prompt, model model oraz proporcje obrazu aspect_ratio, aby wygenerować odpowiedni film. Można zauważyć, że ustawiliśmy tutaj Request Headers, w tym:
  • accept: format odpowiedzi, który chcesz otrzymać; tutaj wpisano application/json, czyli format JSON.
  • authorization: klucz do wywołania API, po uzyskaniu można go bezpośrednio wybrać z listy rozwijanej.
Dodatkowo ustawiono Request Body, w tym:
  • prompt: tekstowy prompt opisujący treść filmu, który chcesz wygenerować, wymagany.
  • model: model generujący film, obecnie obsługiwany jest tylko omni-flash, a domyślnie jest to omni-flash.
  • aspect_ratio: proporcje obrazu generowanego filmu; do wyboru 16:9 (poziomo) lub 9:16 (pionowo), domyślnie 16:9.
  • resolution: opcjonalna rozdzielczość wyjściowa; do wyboru 720p lub 1080p, domyślnie 720p.
  • image_urls: opcjonalna tablica linków do obrazów referencyjnych, używana do ukierunkowania generowania filmu; puste elementy będą ignorowane. Podczas używania video_urls do edycji wideo ten parametr jest wymagany (co najmniej jeden obraz).
  • video_urls: opcjonalna tablica linków do referencyjnych filmów (maksymalnie 1), używana do edycji wideo / referencji wideo; po jej podaniu należy jednocześnie podać co najmniej jeden image_urls.
  • callback_url: adres asynchronicznego callbacku; po ustawieniu API natychmiast zwróci task_id, a po zakończeniu zadania wyśle wynik metodą POST na ten adres.
  • async: opcjonalne; po ustawieniu na true interfejs natychmiast zwróci task_id, bez konieczności podawania callback_url, a następnie wynik można uzyskać przez odpytywanie odpowiedniego interfejsu zapytania o zadanie.
Kliknij przycisk „Try”, aby przeprowadzić test; otrzymany wynik będzie podobny do poniższego:
Zwrócony wynik zawiera wiele pól, opisanych poniżej:
  • success: czy bieżące żądanie generowania filmu zakończyło się powodzeniem.
  • task_id: ID bieżącego zadania generowania filmu.
  • trace_id: ID śledzenia bieżącego żądania, używane do diagnozowania problemów.
  • data: lista wyników wygenerowanych filmów.
    • id: unikalny identyfikator wygenerowanego filmu.
    • video_url: adres linku do wygenerowanego filmu (null, gdy state ma wartość pending).
    • state: status zadania generowania filmu; do wyboru pending / succeeded / failed.
    • aspect_ratio: proporcje obrazu tego filmu, zgodne z parametrami żądania.
    • prompt: prompt użyty do wygenerowania tego filmu.
W przypadku odpowiedzi synchronicznej na najwyższym poziomie zostaną również dołączone pola takie jak started_at, finished_at, elapsed (czas trwania, w sekundach) oraz cost (opłata za bieżące żądanie, w jednostkach Credit). Wystarczy pobrać wygenerowany film na podstawie adresu linku video_url w data wyniku. Odpowiedni kod CURL jest następujący:
Odpowiedni kod Python jest następujący:

Obraz na wideo

Jeśli chcesz wygenerować film na podstawie obrazu referencyjnego, możesz przekazać jeden lub więcej linków do obrazów w image_urls, aby ukierunkować generowanie filmu:

Edycja wideo / wideo referencyjne (wprowadź wideo, wygeneruj wideo)

Obsługiwane jest bezpośrednie „wprowadzenie fragmentu wideo i wygenerowanie nowego wideo”: przekaż link do referencyjnego wideo (maksymalnie 1) w video_urls i jednocześnie podaj co najmniej jeden obraz referencyjny w image_urls, a następnie użyj prompt, aby opisać oczekiwany efekt edycji (zmiana stylu, zmiana sceny, dodawanie lub usuwanie elementów itp.). Poniżej znajduje się pełny, rzeczywisty przykład — przekształcenie filmu ze słonecznej plaży w zimową scenę z intensywnymi opadami śniegu, przy zachowaniu układu plaży, palm i małej łodzi. Edycja wideo trwa dość długo (w tym przykładzie około 6,5 minuty), dlatego została przesłana asynchronicznie przy użyciu async: true:
Po przesłaniu interfejs natychmiast zwraca task_id:
Następnie użyj tego task_id jako id do odpytywania Gemini Tasks API. Po ukończeniu zadania otrzymasz wygenerowane nowe wideo (to rzeczywisty wynik zwrócony w tym przykładzie):
Aby uzyskać wynik w wyższej rozdzielczości, ustaw resolution na 1080p (pozostałe parametry pozostają bez zmian).
Wskazówka: linki do multimediów wejściowych/wyjściowych w przykładach są rzeczywistymi wynikami generowania. Linki do filmów i obrazów wygenerowanych przez platformę mają ograniczony okres ważności i po jego upływie przestaną działać. Po otrzymaniu wyników niezwłocznie pobierz je i zapisz we własnym magazynie danych.
Uwaga: można podać maksymalnie 1 film referencyjny; a gdy podano video_urls, należy podać co najmniej jeden image_urls, w przeciwnym razie zostanie zwrócony następujący błąd parametrów:

Asynchroniczne wywołanie zwrotne

Generowanie filmu 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 ostateczny wynik metodą POST na ten adres:
Natychmiast zwracany wynik jest następujący:

Sprawdzanie wyniku zadania

Jeśli użyto asynchronicznego wywołania zwrotnego lub chcesz aktywnie sprawdzać stan zadania, możesz użyć Gemini Tasks API (POST https://api.acedata.cloud/gemini/tasks), aby sprawdzić najnowszy stan i wynik zadania na podstawie task_id. W treści żądania przekaż task_id zwrócony podczas tworzenia filmu jako id:
Wynik zwracany po ukończeniu zadania jest podobny do poniższego, struktura response.data jest taka sama jak podczas generowania synchronicznego (state podczas generowania ma wartość pending, a video_url ma wartość null):

Obsługa błędów

Jeśli wystąpi problem z żądaniem, API zwróci odpowiedni kod błędu i opis. Najczęstsze z nich to:
  • 400: Nieprawidłowe parametry żądania, na przykład brak prompt lub nieprawidłowa wartość aspect_ratio.
  • 401: Uwierzytelnianie nie powiodło się; token jest nieprawidłowy lub nie odpowiada API.
  • 403: Niewystarczające saldo lub odrzucenie z powodu moderacji treści dla promptu.
  • 500: Błąd usługi lub niepowodzenie generowania.