xAI SDK и автоматично анкетиране
На тази страница
Обновено на 2 ноември 2026 г. въз основа на документацията за видео на xAI и кода на
xai-sdk1.21.0: методите се наричатclient.video.generateиclient.video.extend(редактирането използваgenerateсvideo_url), резултатът излагаurl, забавянето се задава чрезtimedelta, а интервалът на анкетиране по подразбиране е една секунда.awaitизисква асинхронния клиентAsyncClient, а изключениетоVideoGenerationErrorсе импортира отxai_sdk.video. Старата версия използваше методи и модул за изключения, които не съществуват. Източници: Генериране на видео · Редактиране на видео · Разширяване на видео · xai-sdk-python.
Опростете анкетирането със SDK
В предишния урок написахте цикъл за анкетиране на ръка. Това е полезно упражнение за разбиране на жизнения цикъл на генерирането, но също така представлява тридесет реда код за поддържане във всеки проект, със собствена обработка на времевите лимити, случаи на неуспех и преобразувания на статуси. Официалният Python SDK на xAI (pip install xai-sdk) обединява всичко това: Вие подавате заявката, а той се грижи за изчакването.
Едно извикване вместо цикъл
Методът client.video.generate групира подаването, проследяването и извличането. Той връща контрола едва когато видеото е готово или повдига изключение, ако нещо се е объркало.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Генериране текст-към-видео с автоматично анкетиране
video = client.video.generate(
prompt="Изгрев над Алпите, ускорен таймлапс",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Продължителност: {video.duration} с, модел: {video.model}")
Зад тези няколко реда SDK прави точно това, което сте кодирали преди: подава заявката, анкетира статуса всяка секунда по подразбиране и след това връща резултата или повдига изключение в зависимост от изхода.
Една настройка заслужава вниманието Ви още при внедряването: по подразбиране SDK изчаква до 10 минути, преди да се откаже. Това е удобно за нощен производствен скрипт, но твърде дълго за уеб заявка, където потребителят чака отговор. Параметрите timeout и interval, и двата обекти timedelta, задават лимита и ритъма:
from datetime import timedelta
video = client.video.generate(
prompt="Вашето описание",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # макс. 5 минути
interval=timedelta(seconds=5), # една проверка на всеки 5 секунди
)
Ако искате да запазите контрол над изчакването – например за предаване на прогреса – client.video.start подава заявката и връща нейния request_id, който след това се заявява чрез client.video.get.
Обработка на грешки в източника
SDK разграничава неуспехите, което Ви спестява необходимостта да анализирате низове, за да разберете какво се е случило:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Вашето описание",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Видеото е готово: {video.url}")
except VideoGenerationError as e:
print(f"Генерирането се провали [{e.code}]: {e.message}")
except TimeoutError:
print("Времевият лимит е надвишен: увеличете timeout или опростете заявката")
Всяка грешка изисква различна реакция и объркването им води до безполезни цикли за повторни опити или, което е по-лошо, до таксувани генерирания, които не дават резултат.
| Грешка | Причина | Препоръчително действие |
|---|---|---|
VideoGenerationError | Неуспех, сигнализиран от API: отказан промпт, невалиден източник, претоварена услуга… (code, message) | Прочетете кода: поправете заявката или опитайте отново по-късно, ако услугата е била недостъпна |
TimeoutError | Надвишено време за изчакване от страна на клиента | Увеличете timeout или намалете продължителността |
RuntimeError | Отложената заявка е изтекла или е завършила без резултат | Рестартирайте генерирането |
grpc.RpcError | Грешка в транспорта на SDK, включително лимити на честотата (код RESOURCE_EXHAUSTED) и проблеми с ключа | Разделете заявките с backoff или проверете ключа |
SDK използва gRPC: надвишеният лимит на честотата не се появява тук като HTTP код 429, а като grpc.RpcError с код RESOURCE_EXHAUSTED.
Редактиране и разширяване със същата лекота
Редактирането няма отделен метод: това е generate с изходно видео, предадено като video_url (видео до 8,7 секунди, същата изходна продължителност, макс. 720p).
video = client.video.generate(
prompt="Трансформирайте сцената в стил японско аниме",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Разширяването удължава последователност от 2 до 15 секунди със сегмент от 2 до 10 секунди и връща цялото видео:
video = client.video.extend(
prompt="Продължете сцената с панорама надясно",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Обърнете внимание на разликата с REST API: SDK приема видеото като параметър video_url, докато JSON тялото очаква обект video със свойството му url.
Никога не оставяйте видео в облака
SDK не променя нищо относно временния характер на URL адресите на резултатите. Ако кодът Ви просто показва video.url, Вие сте платили за генериране, което скоро ще изчезне. Най-добрата практика е да верижите генерирането и изтеглянето в една и съща функция, така че да стане невъзможно да забравите тази стъпка.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Генерира видео и го запазва локално (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Незабавно изтегляне
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"Видеото е запазено: {output_file}")
return output_file
За съхранение без транзит през Вашия сървър, параметърът storage_options на генерирането депозираща видеото в xAI Files API с избран от Вас срок на валидност.
Генериране на множество видеоклипове едновременно
С асинхронния клиент всяко извикване е корутина, а asyncio.gather стартира цяла партида паралелно. Опцията return_exceptions=True е решаваща тук: без нея една единствена отказана заявка би провалила цялата партида и бихте загубили вече получените резултати.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Генерира множество видеоклипове паралелно."""
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"Заявка {i} се провали: {res}")
else:
print(f"Заявка {i} завършена: {res.url}")
return results
Две предпазни мерки рамкират тази паралелизация. Подаванията консумират Вашия лимит на честотата, броен в заявки в секунда според нивото на Вашия екип (10 за входното ниво за видео модели): за голяма партида ограничете конкурентността с asyncio.Semaphore. Помнете също какво прави и какво не прави паралелизмът: той не ускорява всяко отделно генериране, а само намалява общото време за партидата.
Трябва ли да се откажете от ръчното анкетиране?
Не систематично. Следното сравнение показва къде всеки подход води.
| Аспект | Ръчно анкетиране | SDK |
|---|---|---|
| Сложност | Висока | Ниска |
| Обработка на грешки | За реализиране | Интегрирана |
| Времеви лимит (Timeout) | За реализиране | 10 мин по подразбиране, конфигурируем |
| Интервал на анкетиране | За избор | 1 с по подразбиране, конфигурируем |
| Гъвкавост | Пълна | Стандартна (или start и get) |
| Зависимост | Няма | xAI SDK |
Ръчното анкетиране запазва своята актуалност в две ситуации: когато имате нужда от фин контрол, например за предаване на прогреса към интерфейс в реално време или за интегриране в съществуваща система за опашки, и когато контекстът на внедряването Ви забранява добавянето на допълнителна зависимост.
Ключови изводи
client.video.generateподава, изчаква и връща видеото (url,duration,model); 10-минутен времеви лимит и проверка всяка секунда по подразбиране- Редактирането използва
generateсvideo_url, разширяването използваclient.video.extend VideoGenerationError(отxai_sdk.video),TimeoutErrorиRuntimeErrorразграничават неуспехите; лимитите на честотата идват катоgrpc.RpcError- Винаги изтегляйте видеото веднага след генерирането (временни URL адреси)
- Асинхронният клиент и
asyncio.gatherпаралелизират партида в рамките на лимита на честотата на Вашето ниво