Przejdź do głównej treści
Polski— Wybierz język
Menu

Przepływ asynchroniczny i odpytywanie

Lekcja 10 z 12 Zaktualizowano 2 listopada 2026 Średnio zaawansowani
Na tej stronie
  1. Zrozumienie cyklu życia wideo
  2. Sprawdzanie statusu generowania
  3. Trzy stany, trzy działania
  4. Implementacja odpytywania
  5. Ustawienie interwału odpytywania
  6. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 r. Na podstawie dokumentacji referencyjnej xAI Video API: adres URL znajduje się w polu video.url (a nie video_url), generowanie ma tylko trzy statusy (pending, done, failed, przy czym ostatniemu towarzyszy kod błędu), a limity szybkości wyrażone są w żądaniach na sekundę w zależności od poziomu zespołu. Źródła: Video Generation · Videos Reference · Rate limits.

Zrozumienie cyklu życia wideo

Wszystkie operacje związane z wideo w API xAI są asynchroniczne, a cecha ta kształtuje architekturę Twojej aplikacji bardziej, niż mogłoby się wydawać na pierwszy rzut oka. Wywołanie czatu lub generowanie obrazu zwraca wynik natychmiast; generowanie wideo wymaga jednak znacznego czasu przetwarzania i zwraca jedynie potwierdzenie. To do Ciebie należy implementacja śledzenia: musisz okresowo odpytywać status zadania, wykrywać jego zakończenie i pobierać plik. Pełny cykl składa się z czterech kroków.

1

Wyślij żądanie

Wykonaj POST do punktu końcowego generowania, edycji lub rozszerzania. Natychmiastowa odpowiedź z request_id.

2

Odpytuj status

Wykonuj GET /v1/videos/{request_id} w regularnych odstępach. Pole progress zmienia się od 0 do 100.

3

Pobierz wynik

Gdy status to done (progress = 100), adres URL wideo jest dostępny.

4

Pobierz natychmiast

Adres URL wideo jest tymczasowy. Pobierz go tak szybko, jak to możliwe.

Sprawdzanie statusu generowania

Śledzenie postępu polega na wykonaniu prostego żądania GET do punktu końcowego statusu, przy użyciu identyfikatora otrzymanego podczas przesyłania żądania.

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Odpowiedź udostępnia następujące przydatne informacje:

  • status : bieżący stan generowania
  • progress : liczba całkowita od 0 do 100 wskazująca postęp
  • video.url : adres URL wideo, znajdujący się w obiekcie video, obecny gdy status to done, wraz z czasem trwania (video.duration)
  • video.respect_moderation : wartość logiczna wskazująca, czy treść jest zgodna z polityką moderacji
  • error : w przypadku niepowodzenia zawiera kod (invalid_argument, permission_denied, failed_precondition, service_unavailable lub internal_error) oraz wiadomość
  • usage.cost_in_usd_ticks : koszt żądania, wyrażony w dziesięciomiliardowych częściach dolara

Pole progress zasługuje na uwagę: nie steruje ono Twoją logiką kontrolną, która zawsze powinna opierać się na status, ale jest bezcenne dla interfejsu użytkownika. Wyświetlenie „62%“ zamiast statycznego wskaźnika ładowania całkowicie zmienia postrzeganie oczekiwania, które może trwać kilka minut.

Trzy stany, trzy działania

StatusProgressZnaczenie
pending0-99Generowanie w toku
done100Zakończono, adres URL dostępny
failedbrakGenerowanie nieudane

Dopóki status to pending, generowanie trwa: po prostu kontynuujesz odpytywanie w regularnych odstępach, przekazując wartość progress do swojego interfejsu. Gdy zmieni się on na done, wideo jest gotowe i jedynym zadaniem jest odczytanie video.url oraz natychmiastowe pobranie pliku – adresy URL są tymczasowe, a dokumentacja nie precyzuje ich czasu życia, co uniemożliwia przechowywanie ich w bazie danych do późniejszego użycia.

Na koniec status failed wskazuje na niepowodzenie produkcji, a pole error informuje, jakie ono było. Rozróżnienie to ma znaczenie dla kolejnych kroków: service_unavailable (usługa tymczasowo przeciążona) lub internal_error uzasadniają ponowną próbę później, podczas gdy invalid_argument lub permission_denied – odrzucony prompt, nieprawidłowy obraz lub wideo źródłowe – wymagają najpierw poprawienia żądania. Python SDK z kolei również sygnalizuje poprzez błąd sytuację, w której odroczone żądanie wygasło przed jego pobraniem.

Implementacja odpytywania

Wersja synchroniczna mieści się w jednej funkcji. Wykonuje pętlę aż do przekroczenia limitu czasu, wychodzi wcześniej w przypadku niepowodzenia, zgłaszając jego kod, i zwraca adres URL, gdy tylko wideo będzie gotowe.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Czekaj na zakończenie generowania wideo."""
    headers = {"Authorization": f"Bearer {api_key}"}
    debut = time.time()

    while time.time() - debut < timeout:
        resp = httpx.get(
            f"https://api.x.ai/v1/videos/{request_id}",
            headers=headers
        ).json()

        status = resp.get("status")
        progress = resp.get("progress", 0)

        if status == "done":
            return resp["video"]["url"]
        elif status == "failed":
            erreur = resp.get("error", {})
            raise RuntimeError(f"Generation failed [{erreur.get('code')}] : {erreur.get('message')}")

        print(f"In progress... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Timeout after {timeout} seconds")

W usłudze obsługującej wiele żądań jednocześnie, ta blokująca wersja staje się wąskim gardłem: każde oczekiwanie unieruchamia wątek na minuty. Przejście na wersję asynchroniczną uwalnia pętlę zdarzeń między zapytaniami i pozwala śledzić dziesiątki generowań równolegle.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Asynchroniczna wersja odpytywania."""
    headers = {"Authorization": f"Bearer {api_key}"}
    async with httpx.AsyncClient() as client:
        debut = asyncio.get_event_loop().time()

        while asyncio.get_event_loop().time() - debut < timeout:
            resp = await client.get(
                f"https://api.x.ai/v1/videos/{request_id}",
                headers=headers
            )
            data = resp.json()

            if data["status"] == "done":
                return data["video"]["url"]
            elif data["status"] == "failed":
                raise RuntimeError(f"Generation failed : {data.get('error')}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Timeout")

Ustawienie interwału odpytywania

Wybór interwału to balans między responsywnością a unikaniem zbędnych żądań. Pięć sekund to dobry kompromis w większości przypadków. Przy długich generowaniach – od dziesięciu do piętnastu sekund wideo – interwał dziesięciu do piętnastu sekund między odpytaniami w zupełności wystarczy i redukuje ruch sieciowy. Z kolei w aplikacji interaktywnej, gdzie użytkownik obserwuje pasek postępu, uzasadnione jest skrócenie go do dwóch lub trzech sekund. Poniżej jednej sekundy jednak niczego nie przyspieszysz: generowanie przebiega we własnym tempie, a Ty jedynie mnożysz żądania bez potrzeby.

Kluczowe wnioski

  • Wszystkie operacje wideo są asynchroniczne: POST do przesłania, GET do pobrania
  • Trzy możliwe statusy: pending, done, failed (z kodem błędu)
  • Pole progress (0-100) pozwala śledzić postęp
  • Zaimplementuj limit czasu i interwał odpytywania dostosowany do Twojego przypadku użycia
  • Adresy URL wideo są tymczasowe: pobierz je natychmiast