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

Kuvamuodot: URL ja Base64

Oppitunti 1 / 12 Päivitetty 3. marraskuuta 2026 Aloittelija
Tällä sivulla
  1. Kuvien lähettäminen Grokille
  2. Suora URL-osoite
  3. Base64-koodattu (Data URI)
  4. URL:n ja Base64:n keskeiset erot
  5. Tekstin ja kuvien yhdistäminen
  6. Keskeiset asiat

Päivitetty 3. marraskuuta 2026. Responses API:ssa input_image- ja input_text-objektit sijoitetaan {"role": "user", ...} -viestin content-kenttään, ei suoraan input-kenttään. Python-esimerkki kutsui aiemmin client.responses.create()-metodia xai-sdk-asiakkaalla, jota tällä ei ole, ja kirjoitti API-avaimen suoraan koodiin: nyt se käyttää SDK:n user(...)- ja image(...)-funktioita, ja avain luetaan ympäristömuuttujasta. Lisätty xAI:n varoitus historian tallentamisesta. Koodi testattu versiolla xai-sdk 1.21.0. Lähde: Image Understanding.

Kuvien lähettäminen Grokille

Grok analysoi kuvaa Grok-mallit versiosta grok-4.5 eteenpäin sisältävät näkökyvyn. Voit lähettää yhden tai useamman kuvan API-pyyntöihisi, ja malli analysoi ne vastatakseen kysymyksiisi. Tätä kutsutaan kuvien ymmärtämiseksi tai multimodaaliseksi näöksi.

Ennen kuin sukellat käyttötapauksiin, on hallittava kaksi xAI API:n tukemaa kuvien lähetysmuotoa.

2
Tuetut muodot
20 MiB
Enimmäiskoko per kuva
JPG/PNG
Hyväksytyt muodot
Rajoittamaton
Kuvien määrä

Suora URL-osoite

Yksinkertaisin tapa on antaa kuvan julkinen URL-osoite. Malli lataa ja analysoi sen automaattisesti.

Responses API:n (päätepiste) kanssa:

{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_image",
          "image_url": "https://exemple.com/photo-produit.jpg"
        },
        {
          "type": "input_text",
          "text": "Describe this image in detail."
        }
      ]
    }
  ]
}

xAI suosittelee, ettet tallenna pyyntö- ja vastaushistoriaa palvelimilleen lähettäessäsi kuvia, muuten pyyntö voi epäonnistua: käytä Responses API:ssa arvoa "store": false.

Chat Completions API:n (vanhentunut, OpenAI-yhteensopiva) kanssa:

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo-produit.jpg"
          }
        },
        {
          "type": "text",
          "text": "Describe this image in detail."
        }
      ]
    }
  ]
}

URL-osoitteen on viitattava julkisesti saatavilla olevaan kuvatiedostoon. Jos kuva on tunnistautumisen takana tai suojatulla CDN:llä, käytä sen sijaan Base64-muotoa.

Base64-koodattu (Data URI)

Toinen muoto sisältää kuvan koodaamisen suoraan pyyntöön Base64-merkkijonona, jota edeltää MIME-etuliite. Tämä on ihanteellinen tapa käsitellä paikallisia kuvia, kuvakaappauksia tai dynaamisesti luotuja tiedostoja.

{
  "type": "input_image",
  "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

Etuliite data:image/jpeg;base64, kertoo mallille kuvan MIME-tyypin. Säädä se muodon mukaan:

  • data:image/jpeg;base64, JPG/JPEG-tiedostoille
  • data:image/png;base64, PNG-tiedostoille

Kuvan koodaus Pythonilla

import base64

with open("photo.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

image_url = f"data:image/jpeg;base64,{image_data}"

Koodaus JavaScriptillä/Node.js:llä

import { readFileSync } from 'fs';

const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;

URL:n ja Base64:n keskeiset erot

Kriteeri URL Base64
Pyynnön koko Kevyt (vain URL) Raskas (+33 % alkuperäiseen tiedostoon verrattuna)
Saatavuus Vaaditaan julkinen kuva Toimii minkä tahansa paikallisen tiedoston kanssa
Viive Palvelimen lataus Tieto suoraan pyynnössä
Tyypillinen käyttötarkoitus Verkkokuvat, CDN, pilvitallennus Paikalliset tiedostot, kuvakaappaukset, lataukset

Tekstin ja kuvien yhdistäminen

Viestin content hyväksyy sekamuotoisen taulukon input_image- ja input_text-objekteista missä tahansa järjestyksessä: voit vuorotella tekstiä ja kuvia vapaasti. Natiivilla xAI SDK:lla sama viesti rakennetaan funktiolla user(), joka hyväksyy tekstiä ja kuvia, jotka on luotu funktiolla image() peräkkäin:

from xai_sdk import Client
from xai_sdk.chat import image, user

client = Client()  # avain luettu XAI_API_KEY-ympäristömuuttujasta

chat = client.chat.create(model="grok-4.5")
chat.append(
    user(
        "Vertaa näitä kahta valokuvaa:",
        image(image_url="https://exemple.com/photo1.jpg", detail="high"),
        image(image_url="https://exemple.com/photo2.jpg", detail="high"),
        "Mitkä ovat tärkeimmät erot?",
    )
)

response = chat.sample()
print(response.content)

image() hyväksyy julkisen URL-osoitteen tai Base64 Data URI:n.

Keskeiset asiat

  • Kaksi kuvamuotoa on tuettu: Suora URL ja Base64 (Data URI)
  • Hyväksytyt muodot ovat vain JPG, JPEG ja PNG
  • Yhden kuvan koko ei saa ylittää 20 MiB:tä
  • Kuvien määrä pyyntöä kohden on rajoittamaton
  • Responses API sijoittaa input_image-objektin viestin content-kenttään; Chat Completions käyttää image_url-osia; xAI SDK käyttää image()-funktiota user()-funktion sisällä
  • Suosi URL:ää julkisille kuville ja Base64:ää paikallisille tiedostoille