Przejdź do głównej treści
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, aby uzyskać swój token API, który należy zachować na przyszłość. 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.
📘 Pełna dokumentacja: Grok Videos Generation API →

Opis modeli

Za pomocą model można wybrać jeden z poniższych czterech publicznych modeli. Ich możliwości i sposób rozliczania są następujące:
  • grok-imagine-video-1.5-fast:reverse (domyślny): obsługuje generowanie wideo z tekstu (należy przekazać tylko prompt) oraz generowanie wideo z obrazu (należy przekazać image_url), długość 6–30 sekund, rozliczanie według przedziałów czasu trwania; najtańszy.
  • grok-imagine-video:reverse: obsługuje generowanie wideo z tekstu i obrazu, długość 1–15 sekund, rozliczanie według liczby sekund wygenerowanego materiału.
  • grok-imagine-video:official: obsługuje generowanie wideo z tekstu i obrazu, długość 1–15 sekund, rozliczanie według liczby sekund wygenerowanego materiału, wyższa jakość obrazu.
  • grok-imagine-video-1.5:official: obsługuje wyłącznie generowanie wideo z obrazu, wymaga przekazania image_url, długość 1–15 sekund, obsługuje maksymalnie 1080p, rozliczanie według liczby sekund wygenerowanego materiału.

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:
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:
Odpowiedni kod Python wygląda następująco:

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:

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:

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:
Natychmiast zwrócony wynik wygląda następująco:

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 (POST https://api.acedata.cloud/grok/tasks) w celu sprawdzenia najnowszego statusu i wyników zadania na podstawie task_id.

Informacje o rozliczeniach

Sposób rozliczania tej usługi jest określany przez model:
  • grok-imagine-video-1.5-fast:reverse: rozliczanie według przedziałów czasu trwania, niezależnie od rozdzielczości — 6–10 sekund, 11–20 sekund i 21–30 sekund odpowiadają różnym poziomom cenowym.
  • grok-imagine-video:reverse: rozliczanie według „sekund wygenerowanego materiału”, cena całkowita = cena jednostkowa × duration.
  • grok-imagine-video:official i grok-imagine-video-1.5:official: rozliczanie według „sekund wygenerowanego materiału”; im wyższa rozdzielczość, tym wyższa cena jednostkowa. W przypadku modeli oficjalnych opłata jest naliczana nawet wtedy, gdy moderacja treści zakończy się niepowodzeniem.
Dokładne ceny jednostkowe znajdują się na stronie cennika. Nieudane żądania nie są płatne i nie zużywają bezpłatnego 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.