xAI SDK i automatyczne odpytywanie
Na tej stronie
Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji wideo xAI oraz kodu
xai-sdkw wersji 1.21.0: metody toclient.video.generateiclient.video.extend(edycja wykorzystujegeneratez parametremvideo_url), wynik udostępniaurl, opóźnienie ustawia się za pomocątimedelta, a domyślny interwał odpytywania wynosi jedną sekundę. Słowo kluczoweawaitwymaga klienta asynchronicznegoAsyncClient, a wyjątekVideoGenerationErrorimportuje się z modułuxai_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łąd | Przyczyna | Zalecane działanie |
|---|---|---|
VideoGenerationError | Niepowodzenie 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 |
TimeoutError | Przekroczono czas oczekiwania po stronie klienta | Zwiększ timeout lub skróć czas trwania wideo |
RuntimeError | Odroczone żądanie wygasło lub zakończyło się bez wyniku | Uruchom generowanie ponownie |
grpc.RpcError | Błąd transportu SDK, w tym limity szybkości (kod RESOURCE_EXHAUSTED) i problemy z kluczem | Rozdziel żą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.
| Aspekt | Ręczne odpytywanie | SDK |
|---|---|---|
| Złożoność | Wysoka | Niska |
| Obsługa błędów | Do zaimplementowania | Zintegrowana |
| Limit czasu | Do zaimplementowania | Domyślnie 10 min, konfigurowalny |
| Interwał odpytywania | Do wyboru | Domyślnie 1 s, konfigurowalny |
| Elastyczność | Pełna | Standardowa (lub start i get) |
| Zależność | Brak | xAI 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.generatewysyła żądanie, czeka i zwraca wideo (url,duration,model); domyślny limit czasu to 10 minut, a sprawdzanie co 1 sekundę- Edycja wykorzystuje
generatezvideo_url, rozszerzanie używaclient.video.extend VideoGenerationError(zxai_sdk.video),TimeoutErroriRuntimeErrorrozróżniają rodzaje niepowodzeń; limity szybkości przychodzą jakogrpc.RpcError- Zawsze pobieraj wideo natychmiast po wygenerowaniu (tymczasowe adresy URL)
- Klient asynchroniczny i
asyncio.gatherpozwalają na równoległe przetwarzanie partii, w ramach limitu szybkości Twojego poziomu