Kuvamuodot: URL ja Base64
Tällä sivulla
Päivitetty 3. marraskuuta 2026. Responses API:ssa
input_image- jainput_text-objektit sijoitetaan{"role": "user", ...}-viestincontent-kenttään, ei suoraaninput-kenttään. Python-esimerkki kutsui aiemminclient.responses.create()-metodiaxai-sdk-asiakkaalla, jota tällä ei ole, ja kirjoitti API-avaimen suoraan koodiin: nyt se käyttää SDK:nuser(...)- jaimage(...)-funktioita, ja avain luetaan ympäristömuuttujasta. Lisätty xAI:n varoitus historian tallentamisesta. Koodi testattu versiollaxai-sdk1.21.0. Lähde: Image Understanding.
Kuvien lähettäminen Grokille
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.
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-tiedostoilledata: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 viestincontent-kenttään; Chat Completions käyttääimage_url-osia; xAI SDK käyttääimage()-funktiotauser()-funktion sisällä - Suosi URL:ää julkisille kuville ja Base64:ää paikallisille tiedostoille