Instrukcja integracji Gemini Videos Generation API

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:

{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

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:

curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'

Odpowiedni kod Python jest następujący:

import requests

url = "https://api.acedata.cloud/gemini/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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:

{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}

Edycja wideo / film referencyjny (wideo wejściowe, generowanie wideo)

Obsługiwane jest bezpośrednie „wprowadzenie fragmentu wideo i wygenerowanie nowego fragmentu wideo”: przekaż link do filmu referencyjnego w video_urls (maksymalnie 1) i jednocześnie podaj co najmniej jeden obraz referencyjny w image_urls (twardy wymóg upstream), a następnie użyj prompt, aby opisać oczekiwany efekt edycji (zmiana stylu, zmiana sceny, dodawanie lub usuwanie elementów itd.). Poniżej znajduje się kompletny rzeczywisty przykład — zmiana filmu ze słoneczną plażą w zimową scenę z intensywnymi opadami śniegu, przy jednoczesnym zachowaniu układu plaży, palm kokosowych i małej łodzi. Edycja wideo trwa dłużej (w tym przykładzie około 6,5 minuty), dlatego przesłano ją asynchronicznie za pomocą async: true:

{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}

Po przesłaniu interfejs natychmiast zwraca task_id:

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

Następnie użyj tego task_id jako id, aby odpytywać Gemini Tasks API; po ukończeniu zadania można uzyskać nowo wygenerowany film (jest to rzeczywisty wynik zwrócony w tym przykładzie):

{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Jeśli potrzebny jest wynik w wyższej rozdzielczości, można ustawić resolution na 1080p (pozostałe parametry bez zmian).

Wskazówka: linki do mediów wejściowych / wyjściowych w przykładzie są rzeczywistymi wynikami generowania. Linki do filmów i obrazów wygenerowanych przez platformę mają okres przechowywania i wygasną po jego upływie, dlatego po uzyskaniu wyniku należy go niezwłocznie pobrać i zapisać we własnej pamięci masowej.

Uwaga: maksymalnie 1 film referencyjny; ponadto w przypadku podania video_urls należy podać co najmniej jeden image_urls, w przeciwnym razie zostanie zwrócony następujący błąd parametrów:

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}

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:

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}

Natychmiast zwracany wynik jest następujący:

{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

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:

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

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):

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}

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 brakuje prompt lub wartość aspect_ratio jest nieprawidłowa.
401: uwierzytelnianie nie powiodło się, token jest nieprawidłowy lub nie pasuje do API.
403: niewystarczające saldo lub prompt został odrzucony przez moderację treści.
500: wewnętrzny błąd serwera lub niepowodzenie generowania po stronie usługi nadrzędnej.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Instrukcja integracji Gemini Videos Generation API

Proces aplikacji

Podstawowe użycie

Obraz na wideo

Edycja wideo / film referencyjny (wideo wejściowe, generowanie wideo)

Asynchroniczne wywołanie zwrotne

Sprawdzanie wyniku zadania

Obsługa błędów

​Proces aplikacji

​Podstawowe użycie

​Obraz na wideo

​Edycja wideo / film referencyjny (wideo wejściowe, generowanie wideo)

​Asynchroniczne wywołanie zwrotne

​Sprawdzanie wyniku zadania

​Obsługa błędów

Proces aplikacji

Podstawowe użycie

Obraz na wideo

Edycja wideo / film referencyjny (wideo wejściowe, generowanie wideo)

Asynchroniczne wywołanie zwrotne

Sprawdzanie wyniku zadania

Obsługa błędów