Премини към основното съдържание
Български— Изберете език
Меню

xAI SDK и автоматично анкетиране

Урок 11 от 12 Обновен 2 ноември 2026 г. Средно
На тази страница
  1. Опростете анкетирането със SDK
  2. Едно извикване вместо цикъл
  3. Обработка на грешки в източника
  4. Редактиране и разширяване със същата лекота
  5. Никога не оставяйте видео в облака
  6. Генериране на множество видеоклипове едновременно
  7. Трябва ли да се откажете от ръчното анкетиране?
  8. Ключови изводи

Обновено на 2 ноември 2026 г. въз основа на документацията за видео на xAI и кода на xai-sdk 1.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 паралелизират партида в рамките на лимита на честотата на Вашето ниво