Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Päätepiste /v1/videos/generations: Ensimmäinen videosi

Oppitunti 1 / 12 Päivitetty 3. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Videon luominen tekstistä
  2. Pyynnön rakenne
  3. Ensimmäinen end-to-end-kutsu
  4. Ääni oletuksena
  5. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n videodokumentaation perusteella: käytettävissä on kolme videomallia (grok-imagine-video-1.5, sen -lite-versio ja grok-imagine-video), resoluutio yltää 1080p:hen 1.5-malleissa, videoissa on oletusarvoisesti ääniraita (generate_audio), nopeusrajoitukset lasketaan pyyntöinä sekunnissa, ja vanhemmassa versiossa esitelty size-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.

1–15 s
Kesto per video
1080p
Suurin resoluutio
alkaen 0,02 $
Per generoitu sekunti
9
Käytettävissä olevat kuvasuhteet

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 versio grok-imagine-video-1.5-lite (jonka xAI suosittelee yksinkertaisiin videoihin) tai grok-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), 720p tai 1080p – jälkimmäinen renderöityy natiivisti mallilla grok-imagine-video-1.5 teksti-videoksi ja kuva-videoksi -toiminnoissa, saadaan ylöspäin näytteistämällä 720p -lite-versiossa, ja puuttuu mallista grok-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 malleja grok-imagine-video-1.5, sen -lite-versiota tai grok-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": false tuottaa mykän videon