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

Работен поток с асинхронност и периодична проверка

Урок 10 от 12 Обновен 2 ноември 2026 г. Средно
На тази страница
  1. Разберете жизнения цикъл на видеото
  2. Проверка на статуса на генериране
  3. Три състояния, три действия
  4. Внедряване на периодична проверка (Polling)
  5. Задаване на интервала за проверка
  6. Ключови изводи

Обновено на 2 ноември 2026 г. Въз основа на справочната документация на xAI Video API: URL адресът се намира в video.url (не в video_url), едно генериране има само три статуса (pending, done, failed, като последният е придружен от код на грешка), а ограниченията на честотата са изразени в заявки за секунда въз основа на нивото на екипа. Източници: Генериране на видео · Справка за видеоклипове · Ограничения на честотата.

Разберете жизнения цикъл на видеото

Всички операции с видео в xAI API са асинхронни и тази характеристика оформя архитектурата на Вашето приложение повече, отколкото може би очаквате първоначално. Обаждане до чат или генериране на изображение връща резултат незабавно; генерирането на видео обаче изисква значително време за обработка и връща само потвърждение за получаване. Ваша задача е да внедрите проследяване: периодично да заявявате статуса на задачата, да откривате приключването ѝ и да извличате файла. Пълният цикъл се състои от четири стъпки.

1

Изпращане на заявка

POST към крайната точка за генериране, редактиране или разширяване. Незабавен отговор с request_id.

2

Периодична проверка на статуса

GET /v1/videos/{request_id} на редовни интервали. Полето progress се променя от 0 до 100.

3

Извличане на резултата

Когато статусът е done (progress = 100), URL адресът на видеото е наличен.

4

Незабавно изтегляне

URL адресът на видеото е временен. Изтеглете го възможно най-скоро.

Проверка на статуса на генериране

Проследяването включва проста GET заявка към крайната точка за статус, използвайки идентификатора, получен при подаването.

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

Отговорът предоставя следната полезна информация:

  • status : текущото състояние на генерирането
  • progress : цяло число от 0 до 100, показващо напредъка
  • video.url : URL адресът на видеото, намиращ се в обекта video, който присъства, когато статусът е done, заедно с продължителността му (video.duration)
  • video.respect_moderation : булева стойност, указваща дали съдържанието отговаря на политиката за модериране
  • error : в случай на неуспех, код (invalid_argument, permission_denied, failed_precondition, service_unavailable или internal_error) и съобщение
  • usage.cost_in_usd_ticks : цената на заявката, изразена в десетмилиардни части от долара

Полето progress заслужава внимание: то не управлява Вашата контролна логика, която винаги трябва да разчита на status, но е от огромно значение за потребителския интерфейс. Показването на „62%“ вместо статичен индикатор за зареждане променя напълно възприятието за чакане, което може да продължи няколко минути.

Три състояния, три действия

СтатусНапредъкЗначение
pending0-99Генерирането е в процес на изпълнение
done100Завършено, URL адресът е наличен
failedлипсваГенерирането е неуспешно

Докато статусът е pending, генерирането продължава: просто продължавате да правите заявки на редовни интервали, предавайки progress към Вашия интерфейс. Когато се превключи на done, видеото е готово и единственото, което трябва да направите, е да прочетете video.url и да изтеглите файла незабавно – тези URL адреси са временни и документацията не уточнява тяхната продължителност на живот, което забранява съхраняването им в база данни за по-късна употреба.

Накрая, статусът failed показва производствена грешка, а полето error Ви казва каква точно е тя. Разликата е важна за следващите стъпки: service_unavailable (услугата е временно претоварена) или internal_error оправдават повторен опит по-късно, докато invalid_argument или permission_denied – отхвърлен промпт, невалидно изходно изображение или видео – изискват първо коригиране на заявката. От своя страна, Python SDK също сигнализира чрез грешка за отложена заявка, която е изтекла, преди да бъде извлечена.

Внедряване на периодична проверка (Polling)

Синхронната версия се побира в една единствена функция. Тя изпълнява цикъл до изтичане на времето, излиза преждевременно при неуспех, като вдига съответния код, и връща URL адреса веднага щом видеото е готово.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Изчакване на приключването на генерирането на видео."""
    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")

В услуга, обработваща множество заявки едновременно, тази блокираща версия се превръща в тясно място: всяко чакане immobilизира нишка за минути. Асинхронната транспозиция освобождава цикъла на събитията между заявките и Ви позволява да проследявате десетки генерирания паралелно.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Асинхронна версия на периодичната проверка."""
    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")

Задаване на интервала за проверка

Изборът на интервал балансира между отзывчивост и излишни заявки. Пет секунди са добър компромис в повечето случаи. За дълги генерирания – десет до петнадесет секунди видео – десет до петнадесет секунди между проверките са напълно достатъчни и намаляват трафика. Обратно, интерактивно приложение, при което потребителят наблюдава лента за напредък, оправдава намаляването до две или три секунди. Под една секунда обаче няма да ускорите нищо: генерирането протича със собствен темп и Вие само умножавате заявките безсмислено.

Ключови изводи

  • Всички операции с видео са асинхронни: POST за подаване, GET за извличане
  • Три възможни статуса: pending, done, failed (с код на грешка)
  • Полето progress (0-100) Ви позволява да проследявате напредъка
  • Внедрете таймаут и интервал за проверка, подходящи за Вашия случай на употреба
  • URL адресите на видеоклиповете са временни: изтеглете ги незабавно