Päätepiste /v1/videos/generations: Ensimmäinen videosi
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n videodokumentaation perusteella: käytettävissä on kolme videomallia (
grok-imagine-video-1.5, sen-lite-versio jagrok-imagine-video), resoluutio yltää 1080p:hen 1.5-malleissa, videoissa on oletusarvoisesti ääniraita (generate_audio), nopeusrajoitukset lasketaan pyyntöinä sekunnissa, ja vanhemmassa versiossa esiteltysize-parametri ei esiinny API-viitteessä. Lähteet: Videogenerointi · Hinnoittelu.
Videon luominen tekstistä
xAI:n API tarjoaa erityisen videopäätepisteen, POST /v1/videos/generations, joka muuntaa kirjoitetun kuvauksen animoiduksi sekvenssiksi käyttäen yhtä kolmesta Grok Imagine Video -mallista. Ajattele sitä studiona tilauksesta: kuvailet kohtauksen, malli herättää sen liikkeelle, ja saat muokkausvalmiin MP4-tiedoston. Mainosklipit, konseptivisualisoinnit, havainnollistavat animaatiot – kaikki nämä käyttötapaukset kulkevat tämän saman päätepisteen kautta, joten pureudumme siihen ensin.
Yllä oleva esimerkki antaa käsityksen odotetusta lopputuloksesta. Ennen kuin kirjoitat ensimmäisen pyyntösi, pidä mielessäsi neljä rajaa, jotka kehystävät kaikkea näillä malleilla tuottamaasi.
Pyynnön rakenne
Pyynnön sisältö on JSON-objekti, joka on yksinkertaisuudessaan lohduttava. Määrität mallin, kirjoitat kehotteesi ja kehystät tuloksen kolmella muotoiluparametrilla.
{
"model": "grok-imagine-video",
"prompt": "A dolphin jumping in a sunset",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
Tässä on kunkin kentän tarkka merkitys:
- model:
grok-imagine-video-1.5(uusin), sen edullinen versiogrok-imagine-video-1.5-lite(jonka xAI suosittelee yksinkertaisiin videoihin) taigrok-imagine-video(edellinen sukupolvi, jota käytetään edelleen tämän kurssin esimerkeissä) - prompt: tekstikuvaus halutusta kohtauksesta
- duration: kesto sekunteina, välillä 1–15 (oletus 8)
- aspect_ratio: kuvasuhde (oletus 16:9; vaihtoehdot 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
- resolution:
480p(oletus),720ptai1080p– jälkimmäinen renderöityy natiivisti mallillagrok-imagine-video-1.5teksti-videoksi ja kuva-videoksi -toiminnoissa, saadaan ylöspäin näytteistämällä 720p-lite-versiossa, ja puuttuu mallistagrok-imagine-video, joka pysähtyy 720p:hen
Kaksi seikkaa ansaitsee korostamisen heti. Malli grok-imagine-video maksaa 0,050 $ per generoitu sekunti (0,08 $ mallille grok-imagine-video-1.5, 0,02 $ sen -lite-versiolle, hintatiedot 3.11.2026): viiden sekunnin sekvenssi maksaa siis ensimmäisellä mallilla 0,25 $ riippumatta siitä, kuinka monta yritystä siihen tarvittiin. Nopeusrajoitus lasketaan pyyntöinä sekunnissa tiimisi tason mukaan: videomalleille entry-tasolla raja on 10, mikä on mukava marginaali normaaliin käyttöön, mutta muodostuu rajoitteeksi, kun käynnistät massiivisia eriä.
Tärkeintä on, että generointi on asynkronista. POST-kutsusi ei palauta videota: se palauttaa request_id:n, ja sinun tehtäväsi on kysellä tilaa, kunnes tiedosto on valmis. Tämä kyselymekanismi on oman oppituntinsa aihe myöhemmin kurssilla; toistaiseksi riittää, kun muistat välittömän vastauksen olevan kuittaus, ei tulos.
Ensimmäinen end-to-end-kutsu
Siirrytään käytäntöön curlilla. Seuraava pyyntö tilaa viiden sekunnin sekvenssin 720p-resoluutiolla ja maisemaformaattina.
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"
}'
Vastaus mahtuu yhdelle riville:
{
"request_id": "vid_abc123def456"
}
Säilytä tämä tunniste huolella. Se on ainoa tapasi noutaa video generoinnin valmistuttua, ja sovellus, joka kadottaa sen, on maksanut generoinnista, jota se ei koskaan saa käsiinsä. Todellisessa palvelussa kirjaat sen muistiin ennen kuin edes aloitat tilan kyselyn.
Ääni oletuksena
Generoitu video sisältää oletusarvoisesti ääniraidan – malleilla grok-imagine-video-1.5 ja sen -lite-versiolla puhe on synkronoitu huuliliikkeiden kanssa. Mykkävideoon, joka on tarkoitettu esimerkiksi sivuston taustaksi tai editointiin, jossa lisäät oman musiikkisi, lisää pyyntöön "generate_audio": false.
Tuloksen kehystämiseksi API tuntee kuitenkin vain kuvasuhteen (aspect_ratio) ja tarkkuuden (resolution): API-viite ei tarjoa pikselikokoparametria. Kuva-videoksi -toiminnossa tulosteen kuvasuhde seuraa aina lähdekuvan suhdetta.
Keskeiset asiat
- Päätepiste on
POST /v1/videos/generations, käyttäen mallejagrok-imagine-video-1.5, sen-lite-versiota taigrok-imagine-video - Kesto vaihtelee 1–15 sekunnin välillä (oletus 8), resoluutio 480p–1080p (maksimi 720p mallilla
grok-imagine-video) - Hinta lasketaan per generoitu sekunti: 0,020 $ (
-lite), 0,050 $ (grok-imagine-video) tai 0,080 $ (grok-imagine-video-1.5) - Generointi on asynkronista: saat
request_id:n, jota käytät tilan kyselyyn myöhemmin - Käytettävissä on yhdeksän kuvasuhdetta kaikkien formaattien mukauttamiseen
- Ääniraita generoituu oletuksena;
"generate_audio": falsetuottaa mykän videon