> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Instrukcja integracji Gemini Videos Generation API

> Gemini AI API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go do późniejszego użycia.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

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

```json theme={null}
{
  "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:

```shell theme={null}
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:

```python theme={null}
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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

Następnie użyj tego `task_id` jako `id`, aby odpytywać [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks); po ukończeniu zadania można uzyskać nowo wygenerowany film (jest to rzeczywisty wynik zwrócony w tym przykładzie):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/gemini-tasks) (`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`:

```json theme={null}
{
  "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`):

```json theme={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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.