Flux de lucru asincron și interogare periodică
Pe această pagină
Actualizat la 2 noiembrie 2026. Pe baza referinței API Video xAI: URL-ul se găsește în
video.url(nuvideo_url), o generare are doar trei stări (pending,done,failed, ultima fiind însoțită de un cod de eroare), iar limitele de rată sunt exprimate în cereri pe secundă în funcție de nivelul echipei. Surse: Generare video · Referință Videos · Limite de rată.
Înțelegeți ciclul de viață al videoclipului
Toate operațiunile video din API-ul xAI sunt asincrone, iar această caracteristică vă modelează arhitectura aplicației mai mult decât v-ați aștepta la prima vedere. O apelare de chat sau o generare de imagini returnează un rezultat imediat; generarea video, însă, necesită un timp semnificativ de procesare și returnează doar o confirmare de primire. Dvs. sunteți responsabil să implementați urmărirea: interogați periodic starea sarcinii, detectați finalizarea și recuperați fișierul. Ciclul complet constă în patru pași.
Trimiteți cererea
POST către endpoint-ul de generare, editare sau extindere. Răspuns imediat cu un request_id.
Interogați starea (Polling)
GET /v1/videos/{request_id} la intervale regulate. Câmpul progress variază de la 0 la 100.
Recuperați rezultatul
Când starea este done (progress = 100), URL-ul videoclipului este disponibil.
Descărcați imediat
URL-ul videoclipului este temporar. Descărcați-l cât mai curând posibil.
Verificați starea generării
Urmărirea implică o simplă cerere GET către endpoint-ul de stare, folosind identificatorul primit la trimitere.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
Răspunsul expune următoarele informații utile:
- status : starea curentă a generării
- progress : un întreg de la 0 la 100 indicând progresul
- video.url : URL-ul videoclipului, în interiorul obiectului
videoprezent când starea estedone, împreună cu durata sa (video.duration) - video.respect_moderation : un boolean care indică dacă conținutul respectă politica de moderare
- error : în caz de eșec, un cod (
invalid_argument,permission_denied,failed_precondition,service_unavailablesauinternal_error) și un mesaj - usage.cost_in_usd_ticks : costul cererii, în zeci de miliardimi de dolar
Câmpul progress merită o notă: acesta nu conduce logica dumneavoastră de control, care ar trebui să se bazeze întotdeauna pe status, dar este de aur pentru o interfață cu utilizatorul. Afișarea „62%“ în loc de un indicator de încărcare static schimbă complet percepția unei așteptări care poate dura câteva minute.
Trei stări, trei acțiuni
| Status | Progress | Semnificație |
|---|---|---|
pending | 0-99 | Generare în curs |
done | 100 | Complet, URL disponibil |
failed | absent | Generare eșuată |
Atâta timp cât starea este pending, generarea continuă: trebuie doar să continuați interogarea la intervale regulate, redirecționând progress către interfața dumneavoastră. Când trece la done, videoclipul este gata, iar singurul lucru de făcut este să citiți video.url și să descărcați fișierul imediat—aceste URL-uri sunt temporare, iar documentația nu specifică durata lor de viață, ceea ce interzice stocarea lor într-o bază de date pentru utilizare ulterioară.
În final, starea failed indică un eșec al producției, iar câmpul error vă spune despre ce este vorba. Distincția contează pentru ceea ce urmează: service_unavailable (serviciu temporar supraîncărcat) sau internal_error justifică reîncercarea mai târziu, în timp ce invalid_argument sau permission_denied—prompt respins, imagine sau video sursă invalid—necesită corectarea cererii mai întâi. SDK-ul Python, la rândul său, semnalează de asemenea printr-o eroare o cerere amânată care a expirat înainte de a fi recuperată.
Implementați interogarea periodică (Polling)
Versiunea sincronă încap într-o singură funcție. Aceasta execută o buclă până la expirarea timpului limită, iese anticipat în caz de eșec ridicând codul său și returnează URL-ul imediat ce videoclipul este gata.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Așteptați finalizarea generării videoclipului."""
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"Generare eșuată [{erreur.get('code')}] : {erreur.get('message')}")
print(f"În curs... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Timeout după {timeout} secunde")
Într-un serviciu care gestionează multiple cereri simultan, această versiune blocantă devine un gât de sticlă: fiecare așteptare imobilizează un fir de execuție timp de minute. Transpunerea asincronă eliberează bucla de evenimente între interogări și vă permite să urmăriți zeci de generări în paralel.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Versiune asincronă a interogării periodice."""
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"Generare eșuată : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Timeout")
Stabiliți intervalul de interogare
Alegerea intervalului echilibrează reactivitatea cu cererile irosite. Cinci secunde este un compromis bun în majoritatea cazurilor. Pentru generări lungi—zece până la cincisprezece secunde de video—zece până la cincisprezece secunde între interogări sunt suficiente și reduc traficul. Dimpotrivă, o aplicație interactivă în care utilizatorul urmărește o bară de progres justifică scăderea la două sau trei secunde. Sub o secundă, totuși, nu veți accelera nimic: generarea avansează în ritmul propriu, iar dumneavoastră doar multiplicați cererile degeaba.
Puncte cheie
- Toate operațiunile video sunt asincrone: POST pentru trimitere, GET pentru recuperare
- Trei stări posibile: pending, done, failed (cu un cod de eroare)
- Câmpul
progress(0-100) vă permite să urmăriți avansul - Implementați un timeout și un interval de interogare adaptat cazului dumneavoastră de utilizare
- URL-urile video sunt temporare: descărcați-le imediat