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

xAI SDK i automatyczne odpytywanie

Lekcja 11 z 12 Zaktualizowano 2 listopada 2026 Średnio zaawansowani
Na tej stronie
  1. Uprość odpytywanie dzięki SDK
  2. Jedno wywołanie zamiast pętli
  3. Obsługuj błędy u źródła
  4. Edycja i rozszerzanie z taką samą łatwością
  5. Nigdy nie zostawiaj wideo w chmurze
  6. Generuj wiele wideo jednocześnie
  7. Czy warto zrezygnować z ręcznego odpytywania?
  8. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji wideo xAI oraz kodu xai-sdk w wersji 1.21.0: metody to client.video.generate i client.video.extend (edycja wykorzystuje generate z parametrem video_url), wynik udostępnia url, opóźnienie ustawia się za pomocą timedelta, a domyślny interwał odpytywania wynosi jedną sekundę. Słowo kluczowe await wymaga klienta asynchronicznego AsyncClient, a wyjątek VideoGenerationError importuje się z modułu xai_sdk.video. Stara wersja odwoływała się do metod i modułu wyjątków, które nie istnieją. Źródła: Video Generation · Video Editing · Video Extension · xai-sdk-python.

Uprość odpytywanie dzięki SDK

W poprzedniej lekcji napisałeś pętlę odpytującą ręcznie. To użyteczne ćwiczenie, aby zrozumieć cykl życia generowania, ale oznacza też trzydzieści linii kodu do utrzymania w każdym projekcie, wraz z własną obsługą limitów czasu, przypadków błędów i konwersji statusów. Oficjalne SDK Pythona od xAI (pip install xai-sdk) enkapsuluje wszystko to za Ciebie: wysyłasz żądanie, a SDK zajmuje się oczekiwaniem.

Jedno wywołanie zamiast pętli

Metoda client.video.generate grupuje wysłanie żądania, śledzenie postępu i pobranie wyniku. Przejęcie sterowania następuje dopiero, gdy wideo jest gotowe, lub zgłaszany jest wyjątek, jeśli coś poszło nie tak.

import os

import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Generowanie tekstu na wideo z automatycznym odpytywaniem
video = client.video.generate(
    prompt="A sunrise over the Alps, accelerated time-lapse",
    model="grok-imagine-video-1.5",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(video.url)
print(f"Duration: {video.duration} s, model: {video.model}")

Za tymi kilkoma linijkami SDK robi dokładnie to, co wcześniej zakodowałeś: wysyła żądanie, odpytuje status co sekundę (domyślnie), a następnie zwraca wynik lub zgłasza wyjątek w zależności od rezultatu.

Jeden parametr zasługuje na Twoją uwagę już na etapie wdrażania: domyślnie SDK czeka do 10 minut, zanim zrezygnuje. To komfortowe dla nocnych skryptów produkcyjnych, ale zdecydowanie za długo dla żądania sieciowego, w którym użytkownik czeka na odpowiedź. Parametry timeout i interval, będące obiektami timedelta, ustawiają odpowiednio limit czasu i rytm odpytywania:

from datetime import timedelta

video = client.video.generate(
    prompt="Your description",
    model="grok-imagine-video-1.5",
    duration=10,
    timeout=timedelta(minutes=5),   # maks. 5 minut
    interval=timedelta(seconds=5),  # jedno sprawdzenie co 5 sekund
)

Jeśli chcesz zachować kontrolę nad czasem oczekiwania – na przykład aby przekazywać postęp użytkownikowi – metoda client.video.start wysyła żądanie i zwraca jego request_id, które następnie możesz odpytywać za pomocą client.video.get.

Obsługuj błędy u źródła

SDK rozróżnia rodzaje niepowodzeń, co избавia Cię od analizowania ciągów znaków, aby ustalić, co się stało:

from xai_sdk.video import VideoGenerationError

try:
    video = client.video.generate(
        prompt="Your description",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(f"Video ready: {video.url}")
except VideoGenerationError as e:
    print(f"Generation failed [{e.code}]: {e.message}")
except TimeoutError:
    print("Timeout exceeded: increase the timeout or simplify the request")

Każdy błąd wymaga innej reakcji; mylenie ich prowadzi do bezużytecznych pętli ponawiania lub, co gorsza, do obciążonych kosztami generacji, które nic nie dają.

BłądPrzyczynaZalecane działanie
VideoGenerationErrorNiepowodzenie sygnalizowane przez API: odrzucony prompt, nieprawidłowe źródło, przeciążenie usługi… (code, message)Sprawdź kod: popraw żądanie lub spróbuj ponownie później, jeśli usługa była niedostępna
TimeoutErrorPrzekroczono czas oczekiwania po stronie klientaZwiększ timeout lub skróć czas trwania wideo
RuntimeErrorOdroczone żądanie wygasło lub zakończyło się bez wynikuUruchom generowanie ponownie
grpc.RpcErrorBłąd transportu SDK, w tym limity szybkości (kod RESOURCE_EXHAUSTED) i problemy z kluczemRozdziel żądania z wycofaniem wykładniczym (backoff) lub sprawdź klucz

SDK korzysta z gRPC: przekroczony limit szybkości nie pojawia się tutaj jako kod HTTP 429, lecz jako grpc.RpcError z kodem RESOURCE_EXHAUSTED.

Edycja i rozszerzanie z taką samą łatwością

Edycja nie ma dedykowanej metody: używa się generate z wideo źródłowym, przekazanym jako video_url (wideo do 8,7 sekundy, wyjście o tym samym czasie trwania, maks. 720p).

video = client.video.generate(
    prompt="Transform the scene into Japanese anime style",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
)

Rozszerzanie wydłuża sekwencję trwającą od 2 do 15 sekund o segment od 2 do 10 sekund i zwraca pełne wideo:

video = client.video.extend(
    prompt="Continue the scene with a pan to the right",
    model="grok-imagine-video",
    video_url="https://example.com/video.mp4",
    duration=5,
)

Zwróć uwagę na różnicę względem API REST: SDK przyjmuje wideo jako parametr video_url, podczas gdy ciało JSON oczekuje obiektu video z właściwością url.

Nigdy nie zostawiaj wideo w chmurze

SDK nic nie zmienia w tym, że adresy URL wyników są tymczasowe. Jeśli Twój kod jedynie wyświetla video.url, zapłaciłeś za generację, która wkrótce zniknie. Najlepszą praktyką jest połączenie generowania i pobierania w tej samej funkcji, dzięki czemu niemożliwe staje się zapomnienie o tym kroku.

from pathlib import Path

import httpx


async def generate_and_save(client, prompt, output_file, **options):
    """Generuje wideo i zapisuje je lokalnie (client: xai_sdk.AsyncClient)."""
    video = await client.video.generate(
        prompt=prompt,
        model="grok-imagine-video-1.5",
        **options,
    )

    # Natychmiastowe pobranie
    async with httpx.AsyncClient() as http:
        response = await http.get(video.url)
        response.raise_for_status()
        Path(output_file).write_bytes(response.content)

    print(f"Video saved: {output_file}")
    return output_file

W przypadku przechowywania bez przesyłania przez Twój serwer, parametr storage_options generowania umieszcza wideo w xAI Files API z wybranym przez Ciebie terminem wygaśnięcia.

Generuj wiele wideo jednocześnie

Dzięki klientowi asynchronicznemu każde wywołanie jest korutyną, a asyncio.gather uruchamia całą partię równolegle. Opcja return_exceptions=True jest tutaj kluczowa: bez niej pojedyncze odrzucone żądanie spowodowałoby niepowodzenie całej partii i utratę już uzyskanych wyników.

import asyncio
import os

import xai_sdk


async def parallel_generation(requests):
    """Generuje wiele wideo równolegle."""
    client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))
    tasks = [
        client.video.generate(
            prompt=req["prompt"],
            model="grok-imagine-video-1.5",
            duration=req.get("duration", 5),
            aspect_ratio=req.get("aspect_ratio", "16:9"),
        )
        for req in requests
    ]

    results = await asyncio.gather(*tasks, return_exceptions=True)

    for i, res in enumerate(results, 1):
        if isinstance(res, Exception):
            print(f"Request {i} failed: {res}")
        else:
            print(f"Request {i} completed: {res.url}")

    return results

Dwa mechanizmy zabezpieczające ograniczają tę paralelizację. Wysyłanie żądań zużywa Twój limit szybkości, liczony w żądaniach na sekundę zgodnie z poziomem Twojego zespołu (10 na poziomie wejściowym dla modeli wideo): przy dużych partiach ogranicz współbieżność za pomocą asyncio.Semaphore. Pamiętaj też, co paralelizacja robi, a czego nie: nie przyspiesza ona żadnego pojedynczego generowania, a jedynie skraca całkowity czas przetwarzania partii.

Czy warto zrezygnować z ręcznego odpytywania?

Nie zawsze. Poniższe porównanie pokazuje, gdzie każde z podejść sprawdza się najlepiej.

AspektRęczne odpytywanieSDK
ZłożonośćWysokaNiska
Obsługa błędówDo zaimplementowaniaZintegrowana
Limit czasuDo zaimplementowaniaDomyślnie 10 min, konfigurowalny
Interwał odpytywaniaDo wyboruDomyślnie 1 s, konfigurowalny
ElastycznośćPełnaStandardowa (lub start i get)
ZależnośćBrakxAI SDK

Ręczne odpytywanie zachowuje swoją przydatność w dwóch sytuacjach: gdy potrzebujesz precyzyjnej kontroli, na przykład aby przekazywać postęp do interfejsu czasu rzeczywistego lub zintegrować go z istniejącym systemem kolejek, oraz gdy kontekst wdrożenia zabrania dodawania dodatkowej zależności.

Kluczowe wnioski

  • client.video.generate wysyła żądanie, czeka i zwraca wideo (url, duration, model); domyślny limit czasu to 10 minut, a sprawdzanie co 1 sekundę
  • Edycja wykorzystuje generate z video_url, rozszerzanie używa client.video.extend
  • VideoGenerationError (z xai_sdk.video), TimeoutError i RuntimeError rozróżniają rodzaje niepowodzeń; limity szybkości przychodzą jako grpc.RpcError
  • Zawsze pobieraj wideo natychmiast po wygenerowaniu (tymczasowe adresy URL)
  • Klient asynchroniczny i asyncio.gather pozwalają na równoległe przetwarzanie partii, w ramach limitu szybkości Twojego poziomu