Endpoint /v1/videos/generations: Prima dumneavoastră generație video
Pe această pagină
Actualizat la 3 noiembrie 2026 pe baza documentației video xAI: sunt disponibile trei modele video (
grok-imagine-video-1.5, versiunea sa-liteșigrok-imagine-video), rezoluția ajunge până la 1080p la modelele 1.5, videoclipurile au o pistă audio implicită (generate_audio), limitele de rată se numără în cereri pe secundă, iar parametrulsizeprezentat de versiunea veche nu apare în referința API. Surse: Generare video · Prețuri.
Generarea unui videoclip din text
API-ul xAI expune un endpoint dedicat pentru video, POST /v1/videos/generations, care transformă o descriere scrisă într-o secvență animată folosind unul dintre cele trei modele Grok Imagine Video. Gândiți-vă la el ca la un studio la cerere: descrieți o scenă, modelul o pune în mișcare, iar dumneavoastră recuperați un fișier MP4 gata de editare. Clipuri promoționale, vizualizări de concepte, animații ilustrative – toate aceste cazuri de utilizare trec prin acest același endpoint, așa că îl vom diseca mai întâi.
Exemplul de mai sus vă oferă o idee despre rezultatul așteptat. Înainte de a scrie prima dumneavoastră cerere, rețineți cele patru limite care încadrează tot ceea ce produceți cu aceste modele.
Structura cererii
Corpul cererii este un obiect JSON de o simplitate reconfortantă. Declarați modelul, scrieți promptul și încadrați rezultatul cu trei parametri de formatare.
{
"model": "grok-imagine-video",
"prompt": "A dolphin jumping in a sunset",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
Iată semnificația exactă a fiecărui câmp:
- model:
grok-imagine-video-1.5(cel mai nou), versiunea sa economicăgrok-imagine-video-1.5-lite(recomandată de xAI pentru videoclipuri simple) saugrok-imagine-video(generația anterioară, încă folosită în exemplele acestui curs) - prompt: descrierea textuală a scenei dorite
- duration: durata în secunde, între 1 și 15 (implicit 8)
- aspect_ratio: raportul de aspect al imaginii (implicit 16:9; opțiuni: 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
- resolution:
480p(implicit),720psau1080p– acesta din urmă este randat nativ degrok-imagine-video-1.5în text-to-video și image-to-video, obținut prin eșantionare ascendentă (upsampling) de la 720p în versiunea-liteși absent lagrok-imagine-video, care se oprește la 720p
Două aspecte merită subliniate chiar acum. Modelul grok-imagine-video costă 0,050 $ pe secundă de video generat (0,08 $ pentru grok-imagine-video-1.5, 0,02 $ pentru versiunea sa -lite, la data de 3 noiembrie 2026): o secvență de cinci secunde vă va costa astfel 0,25 $ cu primul model, indiferent de câte încercări a fost nevoie pentru a ajunge acolo. Limita de rată se numără în cereri pe secundă, în funcție de nivelul echipei dumneavoastră: 10 la nivelul de intrare pentru modelele video, o marjă confortabilă pentru utilizarea normală, care devine o constrângere atunci când lansați loturi masive.
Cel mai important, generarea este asincronă. Apelul dumneavoastră POST nu returnează un videoclip: returnează un request_id, iar apoi depinde de dumneavoastră să interogați starea până când fișierul este gata. Acest mecanism de interogare (polling) face obiectul unei lecții complete mai târziu în curs; deocamdată, rețineți doar că răspunsul imediat este o confirmare de primire, nu un rezultat.
Un prim apel cap-coadă
Să trecem la practică cu curl. Cererea următoare comandă o secvență de cinci secunde la 720p, în format landscape.
curl -X POST "https://api.x.ai/v1/videos/generations" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video",
"prompt": "A cat playing with a ball of yarn in a bright living room",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}'
Răspunsul încap pe un singur rând:
{
"request_id": "vid_abc123def456"
}
Păstrați acest identificator în siguranță. Este singura dumneavoastră modalitate de a recupera videoclipul odată ce generarea este completă, iar o aplicație care îl pierde a plătit pentru o generare pe care nu o va putea niciodată recupera. Într-un serviciu real, îl înregistrați în jurnal (log) chiar înainte de a începe interogarea.
Audio, implicit
Un videoclip generat include o pistă audio în mod implicit – cu, la grok-imagine-video-1.5 și versiunea sa -lite, vorbire sincronizată cu mișcarea buzelor. Pentru un videoclip mut, destinat de exemplu unui fundal de site sau unei editări în care veți adăuga propria muzică, adăugați "generate_audio": false în cerere.
Pentru a încadra ieșirea, totuși, API-ul cunoaște doar raportul (aspect_ratio) și definiția (resolution): referința API nu oferă niciun parametru de dimensiune în pixeli. În image-to-video, raportul de ieșire urmează întotdeauna raportul imaginii sursă.
Puncte cheie
- Endpointul este
POST /v1/videos/generations, cugrok-imagine-video-1.5, versiunea sa-litesaugrok-imagine-video - Durata variază între 1 și 15 secunde (implicit 8), rezoluția de la 480p la 1080p (maxim 720p cu
grok-imagine-video) - Prețul se calculează pe secundă generată: 0,020 $ (
-lite), 0,050 $ (grok-imagine-video) sau 0,080 $ (grok-imagine-video-1.5) - Generarea este asincronă: primiți un
request_idpe care trebuie să îl interogați ulterior - Sunt disponibile nouă rapoarte de aspect pentru a se adapta tuturor formatelor
- O pistă audio este generată implicit;
"generate_audio": falseoferă un videoclip mut