Salt la conținutul principal
Română— Alege o limbă
Meniu

Endpoint /v1/videos/generations: Prima dumneavoastră generație video

Lecția 1 din 12 Actualizată 3 noiembrie 2026 Intermediar
Pe această pagină
  1. Generarea unui videoclip din text
  2. Structura cererii
  3. Un prim apel cap-coadă
  4. Audio, implicit
  5. Puncte cheie

Actualizat la 3 noiembrie 2026 pe baza documentației video xAI: sunt disponibile trei modele video (grok-imagine-video-1.5, versiunea sa -lite și grok-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 parametrul size prezentat 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.

1-15s
Durată per videoclip
1080p
Rezoluție maximă
de la 0,02 $
Per secundă generată
9
Formate disponibile

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) sau grok-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), 720p sau 1080p – acesta din urmă este randat nativ de grok-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 la grok-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, cu grok-imagine-video-1.5, versiunea sa -lite sau grok-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_id pe 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": false oferă un videoclip mut