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

# Grok Videos Generation API Integracja

> Grok API guide - Ace Data Cloud

Ten dokument przedstawia instrukcje dotyczące integracji Grok Videos Generation API, które może generować filmy Grok Imagine (xAI) na podstawie wprowadzonych tekstowych podpowiedzi, obrazów oraz opcjonalnych obrazów referencyjnych.

## Proces aplikacji

Aby korzystać z Grok Videos Generation API, najpierw przejdź do [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość.

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

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.

**Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Przy pierwszym wniosku przyznawana jest darmowa pula, aby można było skorzystać z doświadczenia; w przypadku niewystarczającej puli można doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin).

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

## Opis modelu

To API wybiera punkt końcowy na podstawie sufiksu nazwy modelu: `:reverse` korzysta z szybkiego/standardowego punktu końcowego (tańszego), `:official` korzysta z oficjalnego punktu końcowego (wyższa jakość obrazu, rozliczane według czasu trwania). Obsługiwane są cztery modele:

* `grok-imagine-video-1.5-fast:reverse` (domyślny): obsługuje filmy generowane z tekstu (tylko `prompt`) oraz filmy generowane z obrazów (przekazując `image_url`), czas trwania 6–30 sekund, rozliczane według czasu trwania, najtańsze.
* `grok-imagine-video:reverse`: obsługuje filmy generowane z tekstu i obrazów, czas trwania 1–15 sekund, rozliczane według czasu trwania.
* `grok-imagine-video:official`: oficjalny punkt końcowy, obsługuje filmy generowane z tekstu i obrazów, czas trwania 1–15 sekund, rozliczane według czasu trwania, wyższa jakość obrazu.
* `grok-imagine-video-1.5:official`: oficjalny punkt końcowy, **obsługuje tylko filmy generowane z obrazów**, **musi** przekazać `image_url`, czas trwania 1–15 sekund, obsługuje maksymalnie `1080p`, rozliczane według czasu trwania.

## Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, wprowadzając podpowiedź `prompt`, model `model` i inne parametry, aby wygenerować odpowiedni film.

Można zauważyć, że ustawiliśmy nagłówki żądania, w tym:

* `accept`: jakiego formatu odpowiedzi oczekujesz, tutaj wpisano `application/json`, czyli format JSON.
* `authorization`: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z rozwijanej listy.

Dodatkowo ustawiono ciało żądania, w tym:

* `prompt`: tekstowa podpowiedź opisująca treść filmu, którą chcesz wygenerować. W przypadku filmów generowanych z tekstu **wymagana**; przy przekazywaniu `image_url` opcjonalna.
* `model`: model generujący film, można wybrać `grok-imagine-video-1.5-fast:reverse` (domyślny), `grok-imagine-video:reverse`, `grok-imagine-video:official` lub `grok-imagine-video-1.5:official`.
* `image_url`: link do obrazu wejściowego dla filmów generowanych z obrazów. Gdy `model` to `grok-imagine-video-1.5:official`, **wymagana**.
* `reference_image_urls`: opcjonalna tablica linków do obrazów referencyjnych, używana do kierowania stylem lub treścią filmu.
* `aspect_ratio`: proporcje generowanego filmu, opcjonalnie `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`.
* `resolution`: rozdzielczość wyjściowa, opcjonalnie `480p` (domyślnie), `720p` lub `1080p`.
* `duration`: czas trwania generowanego filmu (sekundy). `grok-imagine-video-1.5-fast:reverse` ma zakres wartości 6–30, pozostałe modele mają zakres 1–15, domyślnie 6. Zaleca się użycie 6 lub 10 sekund, te dwa standardowe czasy są stosunkowo stabilne.
* `callback_url`: adres zwrotny asynchroniczny, po ustawieniu API natychmiast zwróci `task_id`, a po zakończeniu zadania wynik zostanie przesłany na ten adres.
* `async`: opcjonalnie, ustaw na `true`, aby interfejs natychmiast zwrócił `task_id`, nie ma potrzeby podawania `callback_url`, a następnie można uzyskać wyniki, korzystając z odpowiedniego interfejsu do sprawdzania zadań.

Kliknij przycisk „Try”, aby przetestować, a uzyskany wynik będzie podobny do poniższego:

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

Zwrócony wynik zawiera wiele pól, które są opisane poniżej:

* `success`: czy żądanie generowania filmu zakończyło się sukcesem.
* `task_id`: ID zadania generowania filmu.
* `trace_id`: ID śledzenia tego żądania, używane do rozwiązywania problemów.
* `data`: lista wyników wygenerowanych filmów.
  * `id`: unikalny identyfikator wygenerowanego filmu.
  * `video_url`: adres URL wygenerowanego filmu.
  * `state`: stan zadania generowania filmu, opcjonalnie `pending` / `succeeded` / `failed`.

Musimy tylko uzyskać wygenerowany film na podstawie adresu URL `video_url` w `data`.

Odpowiedni kod CURL wygląda następująco:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/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": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

Odpowiedni kod Python wygląda następująco:

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/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": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

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

## Filmy generowane z obrazów

Jeśli chcesz wygenerować film na podstawie jednego obrazu wejściowego, możesz przekazać `image_url`. Używając `grok-imagine-video-1.5:official`, musisz podać to pole:

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## Wskazówki dotyczące obrazów referencyjnych

Jeśli chcesz użyć jednego lub więcej obrazów referencyjnych do kierowania stylem lub treścią filmu, możesz przekazać tablicę linków do obrazów w `reference_image_urls`:

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## Asynchroniczny zwrot

Generowanie wideo wymaga pewnego czasu przetwarzania. Jeśli nie chcesz czekać na długie połączenie, możesz przekazać `callback_url`, w takim przypadku API natychmiast zwróci `task_id`, a po zakończeniu zadania ostateczny wynik zostanie wysłany metodą POST na ten adres:

```json theme={null}
{
  "prompt": "Klatka filmowa kota goniącego motyla w oświetlonym słońcem ogrodzie",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

Natychmiast zwrócony wynik wygląda następująco:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## Sprawdzanie wyników zadania

Jeśli użyto asynchronicznego wywołania zwrotnego lub chcesz aktywnie sprawdzić status zadania, możesz skorzystać z [Grok Tasks API](https://platform.acedata.cloud/documents/grok-tasks) (`POST https://api.acedata.cloud/grok/tasks`) w celu sprawdzenia najnowszego statusu i wyników zadania na podstawie `task_id`.

## Opis rozliczeń

Sposób rozliczeń za tę usługę zależy od `model`:

* `grok-imagine-video-1.5-fast:reverse`: rozliczane według długości, niezależnie od rozdzielczości — `6–10` sekund, `11–20` sekund, `21–30` sekund odpowiadają różnym poziomom cenowym.
* `grok-imagine-video:reverse`: rozliczane według „liczby sekund wyjściowych”, całkowity koszt = cena jednostkowa × `duration`.
* `grok-imagine-video:official` oraz `grok-imagine-video-1.5:official`: oficjalny punkt końcowy, rozliczane według „liczby sekund wyjściowych”, im wyższa rozdzielczość, tym wyższa cena jednostkowa; oficjalne modele będą rozliczane nawet w przypadku niepowodzenia w weryfikacji treści.

Dokładna cena jednostkowa jest określona na stronie z cenami. Nieudane żądania nie są rozliczane i nie zajmują darmowego limitu.

## Obsługa błędów

Gdy wystąpi problem z żądaniem, API zwróci odpowiedni kod błędu i opis, najczęstsze to:

* `400`: błędne parametry żądania, na przykład brak `prompt` w przypadku generowania wideo, lub brak `image_url` w przypadku `grok-imagine-video-1.5:official`, lub `duration` poza zakresem (dla `grok-imagine-video-1.5-fast:reverse` wynosi 6–30, dla pozostałych modeli 1–15).
* `401`: nieudana autoryzacja, token jest nieważny lub niezgodny z API.
* `403`: niewystarczające saldo lub słowa kluczowe trafiły na listę treści odrzuconych w weryfikacji.
* `429`: zbyt wiele żądań, spróbuj ponownie później.
* `500`: niepowodzenie w generowaniu wideo lub awaria usługi.


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