Endpoint /v1/videos/generations: Az első videód
Ezen az oldalon
Frissítve: 2026. november 3. az xAI videós dokumentációja alapján: három videómodell érhető el (
grok-imagine-video-1.5, annak-liteváltozata és agrok-imagine-video), a felbontás az 1.5-ös modelleknél eléri az 1080p-t, a videók alapértelmezetten tartalmaznak hangsávot (generate_audio), a sebességkorlátok másodpercenkénti kérésekben (RPS) számítanak, és a régi verzióban szereplősizeparaméter nem jelenik meg az API-referenciában. Források: Videógenerálás · Árazás.
Videó generálása szövegből
Az xAI API egy dedikált videó-endpointot tesz elérhetővé, a POST /v1/videos/generations útvonalat, amely írott leírásokat alakít át animált szekvenciákká a három Grok Imagine Video modell egyikének segítségével. Tekints rá úgy, mint egy stúdióra, amit igény szerint hívhatsz: leírsz egy jelenetet, a modell életre kelti, te pedig egy szerkesztésre kész MP4-fájlt kapsz vissza. Promóciós klipek, koncepció-vizualizációk, illusztrációs animációk – minden ilyen felhasználási eset ezen az egyetlen endpointon keresztül fut, ezért először ezt boncolgatjuk részletesen.
A fenti példa betekintést nyújt az elvárható kimenetbe. Mielőtt megírnád az első kérésedet, tartsd észben azt a négy határt, amely mindent keretez, amit ezekkel a modellekkel létrehozol.
A kérés felépítése
A kérés törzse egy megnyugtatóan egyszerű JSON-objektum. Megadod a modellt, megírod a promptot (utasítást), és három formázási paraméterrel keretezed az eredményt.
{
"model": "grok-imagine-video",
"prompt": "A dolphin jumping in a sunset",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
Íme az egyes mezők pontos jelentése:
- model:
grok-imagine-video-1.5(a legújabb), annak gazdaságos változata, agrok-imagine-video-1.5-lite(amit az xAI egyszerű videókhoz ajánl), vagy agrok-imagine-video(az előző generáció, amelyet még mindig használunk ebben a tanfolyamban a példákhoz) - prompt: a kívánt jelenet szöveges leírása
- duration: időtartam másodpercben, 1 és 15 között (alapértelmezetten 8)
- aspect_ratio: képarány (alapértelmezetten 16:9; lehetséges értékek: 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
- resolution:
480p(alapértelmezett),720pvagy1080p– utóbbit agrok-imagine-video-1.5natívan rendereli szöveg-ből-videó és kép-ből-videó módban; a-liteverziónál 720p-ből történő felskálázással állítják elő; agrok-imagine-videoesetén pedig nem elérhető, mivel ez a modell maximum 720p-ig megy el
Két pontra most azonnal fel kell hívnom a figyelmedet. A grok-imagine-video modell ára másodpercenként 0,050 USD a generált videó után (a grok-imagine-video-1.5 esetén 0,08 USD, a -lite verziónál 0,02 USD, 2026. november 3-i adatok szerint): egy öt másodperces szekvencia tehát az első modellel 0,25 USD-be kerül, függetlenül attól, hány próbálkozásból sikerült elkészíteni. A sebességkorlát pedig másodpercenkénti kérésekben (RPS) számít, a csapatod szintjétől függően: a videómodelleknél a belépő szinten ez 10 kérés, ami normál használat mellett kényelmes tartalék, de tömeges kötegek indításakor korlátozó tényezővé válhat.
A legfontosabb azonban, hogy a generálás aszinkron. A POST hívásod nem ad vissza videót: egy request_id-t kapsz, és ezután neked kell lekérdezned az állapotot mindaddig, amíg a fájl elkészül. Ezt a lekérdezési mechanizmust a tanfolyam későbbi részében egy teljes leckében tárgyaljuk; most csak jegyezd meg, hogy az azonnali válasz egy visszaigazolás, nem pedig az eredmény maga.
Egy első végpontok közötti (end-to-end) hívás
Lépjünk át a gyakorlatba curl segítségével. Az alábbi kérés egy öt másodperces szekvenciát rendel meg 720p felbontásban, fekvő formátumban.
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"
}'
A válasz elfér egy sorban:
{
"request_id": "vid_abc123def456"
}
Őrizd meg gondosan ezt az azonosítót. Ez az egyetlen módja annak, hogy visszanyerd a videót, ha a generálás befejeződött; egy olyan alkalmazás, amely elveszíti ezt az azonosítót, fizetett egy generálásért, amit sosem fog visszakapni. Egy valós szolgáltatásban még a lekérdezés (polling) elindítása előtt naplózod ezt az értéket.
Hang, alapértelmezetten
A generált videó alapértelmezetten tartalmaz hangsávot – a grok-imagine-video-1.5 és annak -lite változata esetén a beszéd szinkronban van az ajakmozgással. Ha némított videót szeretnél (például weboldal háttérnek, vagy olyan szerkesztéshez, ahol később adsz hozzá saját zenét), add hozzá a "generate_audio": false paramétert a kéréshez.
A kimenet keretezéséhez azonban az API csak az arányt (aspect_ratio) és a felbontást (resolution) ismeri: az API-referencia nem tartalmaz képpontméret-paramétert. Kép-ből-videó esetén a kimeneti arány mindig követi a forráskép arányát.
Főbb megállapítások
- Az endpoint:
POST /v1/videos/generations, használható modellek:grok-imagine-video-1.5, annak-liteváltozata vagy agrok-imagine-video - Az időtartam 1 és 15 másodperc között mozog (alapértelmezetten 8), a felbontás 480p és 1080p között (a
grok-imagine-videoesetén maximum 720p) - Az ár generált másodpercenként számítandó: 0,020 USD (
-lite), 0,050 USD (grok-imagine-video) vagy 0,080 USD (grok-imagine-video-1.5) - A generálás aszinkron: kapsz egy
request_id-t, amit utána lekérdezhetsz - Kilenc képarány áll rendelkezésre, hogy minden formátumhoz igazodhass
- Alapértelmezetten generálódik egy hangsáv; a
"generate_audio": falsebeállítással némított videót kapsz