Работен поток с асинхронност и периодична проверка
На тази страница
Обновено на 2 ноември 2026 г. Въз основа на справочната документация на xAI Video API: URL адресът се намира в
video.url(не вvideo_url), едно генериране има само три статуса (pending,done,failed, като последният е придружен от код на грешка), а ограниченията на честотата са изразени в заявки за секунда въз основа на нивото на екипа. Източници: Генериране на видео · Справка за видеоклипове · Ограничения на честотата.
Разберете жизнения цикъл на видеото
Всички операции с видео в xAI API са асинхронни и тази характеристика оформя архитектурата на Вашето приложение повече, отколкото може би очаквате първоначално. Обаждане до чат или генериране на изображение връща резултат незабавно; генерирането на видео обаче изисква значително време за обработка и връща само потвърждение за получаване. Ваша задача е да внедрите проследяване: периодично да заявявате статуса на задачата, да откривате приключването ѝ и да извличате файла. Пълният цикъл се състои от четири стъпки.
Изпращане на заявка
POST към крайната точка за генериране, редактиране или разширяване. Незабавен отговор с request_id.
Периодична проверка на статуса
GET /v1/videos/{request_id} на редовни интервали. Полето progress се променя от 0 до 100.
Извличане на резултата
Когато статусът е done (progress = 100), URL адресът на видеото е наличен.
Незабавно изтегляне
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%“ вместо статичен индикатор за зареждане променя напълно възприятието за чакане, което може да продължи няколко минути.
Три състояния, три действия
| Статус | Напредък | Значение |
|---|---|---|
pending | 0-99 | Генерирането е в процес на изпълнение |
done | 100 | Завършено, 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 адресите на видеоклиповете са временни: изтеглете ги незабавно