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

Kuvat ja videot eräajossa

Oppitunti 9 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Monimodaalinen massatuotanto
  2. Kuvien eräluonti
  3. Kuvien erämuokkaus
  4. Videoiden eräluonti
  5. Videoiden muokkaus ja jatkaminen
  6. Python SDK:n käyttö
  7. Monimodaalisen sisällön hinnoittelu
  8. Tulosten URL-osoitteiden vanheneminen
  9. Sekoitettu monimodaalinen putki
  10. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: eräalennus on 20 % tukikelpoisissa tekstimalleissa (ei 50 %), esimerkit noudattavat REST API:a ja virallista xai-sdk:ta (client.batch.*; xAI:n erä-API ei käytä OpenAI-muotoa, joten OpenAI SDK ei sovellu), ja Responses API on ensisijainen Chat Completionsiin nähden, joka on xAI:lla vanhentunut päätepiste. Lähteet: Batch API · REST Reference · Batch Pricing.

Monimodaalinen massatuotanto

Erä-API ei rajoitu pelkkään tekstiin. Voit lähettää kuvien luonti- ja muokkauspyyntöjä sekä videoiden luonti-, muokkaus- ja jatkamispyyntöjä. Tämä mahdollistaa kokonaisten monimodaalisten putkien rakentamisen: kirjoita kuvaukset ja tuota niitä vastaavat visuaaliset elementit yhdessä operaatiossa.

Kuvien eräluonti

Päätepiste /v1/images/generations toimii eräajossa täsmälleen kuten synkronisessa tilassa. Valitse muoto parametrilla aspect_ratio, tarkkuus parametrilla resolution ("1k", "1.5k" tai "2k") ja kuvien määrä parametrilla n:

{"custom_id": "img-001", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Minimalist logo for a fintech startup, white background, vector style", "n": 1, "aspect_ratio": "1:1", "resolution": "1k"}}
{"custom_id": "img-002", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Isometric illustration of a datacenter", "n": 1, "aspect_ratio": "16:9", "resolution": "1k"}}

Kuvien erämuokkaus

Päätepiste /v1/images/edits muokkaa olemassa olevaa kuvaa, joka välitetään image-objektissa: joko url (julkinen osoite tai base64-koodattu data) tai ladatun tiedoston file_id.

{"custom_id": "edit-001", "method": "POST", "url": "/v1/images/edits", "body": {"model": "grok-imagine-image-2.0", "prompt": "Replace the background with a solid white background", "image": {"url": "https://example.com/photo.jpg"}}}

Erätilassa muokkaus auttaa käsittelemään kuvastoja: taustojen yhdenmukaistaminen, elementtien lisääminen tai saman retusoinnin soveltaminen satoihin kuviin kerralla.

Videoiden eräluonti

Päätepiste /v1/videos/generations (tai /v1/videos) luo videoita, joiden kesto on 1–15 sekuntia (duration, oletus 8), resoluutioina 480p, 720p tai 1080p:

{"custom_id": "vid-001", "method": "POST", "url": "/v1/videos/generations", "body": {"model": "grok-imagine-video-1.5", "prompt": "Smooth animation of a bar chart growing progressively", "duration": 8, "resolution": "720p"}}

Videoiden käsittely on raskaampaa kuin tekstin tai kuvien, joten nämä pyynnöt voivat kestää eräajossa pidempään.

Videoiden muokkaus ja jatkaminen

Päätepiste /v1/videos/edits muokkaa olemassa olevaa videota, ja /v1/videos/extensions jatkaa sitä 2–10 sekunnin pätkällä. Välitä lähdevideo video-objektissa (.mp4-tiedoston URL-osoite tai file_id):

{"custom_id": "vid-edit-001", "method": "POST", "url": "/v1/videos/edits", "body": {"model": "grok-imagine-video", "prompt": "Slow down the scene", "video": {"url": "https://example.com/clip.mp4"}}}
{"custom_id": "vid-ext-001", "method": "POST", "url": "/v1/videos/extensions", "body": {"model": "grok-imagine-video", "prompt": "The camera slowly pulls back and reveals a sunset", "video": {"url": "https://example.com/clip.mp4"}, "duration": 6}}

Python SDK:n käyttö

SDK valmistelee nämä pyynnöt omilla metodeillaan ja lisää ne erään aivan kuten tekstipyyntökin:

from xai_sdk import Client

client = Client()
batch = client.batch.create(batch_name="catalog_visuals")

requetes = [
    client.image.prepare(
        prompt="Product shot of wireless headphones, dark background, studio lighting",
        model="grok-imagine-image-2.0",
        batch_request_id="prod-42-img",
    ),
    client.video.prepare(
        prompt="The headphones rotate slowly on a turntable, dramatic lighting",
        model="grok-imagine-video-1.5",
        batch_request_id="prod-42-vid",
    ),
]
client.batch.add(batch_id=batch.batch_id, batch_requests=requetes)

Monimodaalisen sisällön hinnoittelu

Tärkeä huomio: eräalennus koskee vain tukikelpoisia tekstimalleja. Kuvista ja videoista veloitetaan normaali hinta, vaikka ne olisivat eräajossa – 2. marraskuuta 2026 alkaen hinta on 0,04 $ kuvalta mallilla grok-imagine-image-2.0 (0,02 $ mallilla grok-imagine-image) ja 0,08 $ videosekunnilta mallilla grok-imagine-video-1.5 (0,02 $ -lite-versiossa, 0,05 $ mallilla grok-imagine-video).

Eräajojen hyöty monimodaalisessa sisällössä ei ole hinnassa vaan operatiivisuudessa: voit lähettää satoja luontipyyntöjä yhdessä operaatiossa hallitsematta yhtä monta erillistä kutsua tai törmäämättä nopeusrajoituksiin.

Tulosten URL-osoitteiden vanheneminen

Kuva- ja videotulokset toimitetaan allekirjoitettuina URL-osoitteina, jotka vanhenevat tunnin kuluttua. Tämä on kriittinen rajoite: lataa tiedostot heti, kun saat tulokset.

import mimetypes

import requests


def telecharger_medias(resultats, dossier):
    """Downloads images and videos as soon as results are retrieved."""
    for r in resultats:
        reponse = r.proto.response
        if reponse.HasField("image_response"):
            url = r.image_response.url
        elif reponse.HasField("video_response"):
            url = r.video_response.url
        else:
            continue  # text result
        fichier = requests.get(url, timeout=120)
        fichier.raise_for_status()
        type_mime = fichier.headers.get("Content-Type", "").split(";")[0]
        extension = mimetypes.guess_extension(type_mime) or ".bin"
        with open(f"{dossier}/{r.batch_request_id}{extension}", "wb") as f:
            f.write(fichier.content)

Älä koskaan säilytä allekirjoitettuja URL-osoitteita myöhempää käyttöä varten: tallenna tiedostot omaan tallennustilaasi (S3, GCS, paikallinen levy).

Sekoitettu monimodaalinen putki

Konkreettinen käyttötapahtuma: tuota täydelliset tuotesivut, teksti ja visuaalisuus, samassa erässä:

{"custom_id": "prod-42-desc", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "Write a marketing description for a high-end wireless headphone.", "max_output_tokens": 300}}
{"custom_id": "prod-42-img", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Product shot of premium wireless headphones, dark gradient background, studio lighting"}}

Yhteinen etuliite tunnisteissa (prod-42-desc, prod-42-img) helpottaa saman tuotteen teksti- ja kuvatulosten ryhmittelyä.

Keskeiset asiat

  • Kuvat (luonti, muokkaus) ja videot (luonti, muokkaus, jatkaminen) toimivat eräajossa
  • Parametrit vastaavat API:a: aspect_ratio, resolution, image- ja video-objektit
  • Kuvista ja videoista veloitetaan normaali hinta ilman eräalennuksia
  • Allekirjoitetut tulososoitteet vanhenevat tunnissa: lataa ne välittömästi
  • Yhteinen etuliite tunnisteissa ryhmittää saman tuotteen tulokset