Pildiformaadid: URL ja Base64
Sellel lehel
Uuendatud 3. novembril 2026. Responses API kasutamisel lisatakse
input_imagejainput_textobjektid sõnumi{"role": "user", ...}väljalecontent, mitte otse väljaleinput. Eelmine Pythoni näide kutsusxai-sdkkliendil meetoditclient.responses.create(), mida sellel kliendil tegelikult pole, ja sisaldas API võtit koodis: nüüd kasutatakse SDKst funktsiooneuser(...)jaimage(...), lugedes võtme keskkonnamuutujatest. Lisatud on xAI hoiatus ajaloo salvestamise kohta. Kood on kontrollitud versioonigaxai-sdk1.21.0. Allikas: Image Understanding.
Piltide saatmine Grokile
Alates mudelist grok-4.5 sisaldavad Groki mudelid nägemisvõimet. Saad oma API päringutes saata ühe või mitu pilti ning mudel analüüsib neid, et vastata sinu küsimustele. Seda nimetatakse piltide mõistmiseks ehk multimodaalseks nägemiseks.
Enne kasutusjuhtude juurde asumist on oluline omandada xAI API poolt toetatud kaks pildi esitamise formaati.
Otse URL
Lihtsaim meetod on sisestada pildi avalik URL. Mudel laeb pildi alla ja analüüsib seda automaatselt.
Kasutades Responses API-t (peamine lõpp-punkt):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Kirjelda seda pilti üksikasjalikult."
}
]
}
]
}
xAI soovitab piltide saatmisel mitte salvestada päringute ja vastuste ajalugu nende serveritesse, vastasel juhul võib päring nurjuda: kasutades Responses API-t, lisa "store": false.
Kasutades Chat Completions API-t (vananenud, OpenAI-ga ühilduv):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Kirjelda seda pilti üksikasjalikult."
}
]
}
]
}
URL peab viitama avalikult ligipääsetavale pildifailile. Kui pilt on kaitstud autentimisega või asub kaitstud CDN-is, kasuta selle asemel Base64 formaati.
Base64 kodeering (Data URI)
Teine formaat hõlmab pildi kodeerimist otse päringusse Base64 stringina, millele eelneb MIME prefiks. See on ideaalne meetod kohalike piltide, ekraanitõmmiste või dünaamiliselt genereeritud failidega töötamisel.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
Prefiks data:image/jpeg;base64, annab mudelile teada pildi MIME-tüübi. Kohanda seda vastavalt formaadile:
data:image/jpeg;base64,JPG/JPEG failide jaoksdata:image/png;base64,PNG failide jaoks
Pildi kodeerimine Pythonis
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}"
Kodeerimine JavaScriptis/Node.js-is
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Peamised erinevused URL-i ja Base64 vahel
| Kriteerium | URL | Base64 |
|---|---|---|
| Päringu suurus | Kerge (ainult URL) | Raske (+33% võrreldes algse failiga) |
| Ligipääsetavus | Vajalik avalik pilt | Toimib iga kohaliku failiga |
| Latentsus | Server laeb alla | Andmed otse päringus |
| Tüüpiline kasutusjuhtum | Veebipildid, CDN, pilvesalvestus | Kohalikud failid, ekraanitõmmised, üleslaadimised |
Teksti ja piltide segamine
Sõnumi väli content aktsepteerib segatud massiivi objektidest input_image ja input_text suvalises järjekorras: saad vabalt vaheldumisi lisada teksti ja pilte. Kasutades nativset xAI SDK-d, ehitatakse sama sõnum funktsiooniga user(), mis aktsepteerib järjestikku teksti ja funktsiooniga image() loodud pilte:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # võti loetakse muutujast XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Võrdle neid kahte fotot:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"Millised on peamised erinevused?",
)
)
response = chat.sample()
print(response.content)
Funktsioon image() aktsepteerib avalikku URL-i või Base64 Data URI-d.
Peamised punktid
- Toetatud on kaks pildiformaati: Otse URL ja Base64 (Data URI)
- Lubatud on ainult formaadid JPG, JPEG ja PNG
- Ükski pilt ei tohi ületada suurust 20 MiB
- Piltide arv päringu kohta on piiramatu
- Responses API paigutab
input_imagesõnumi väljalecontent; Chat Completions kasutab osiimage_url; xAI SDK kasutab funktsiooniimage()funktsiooniuser()sees - Eelista avalike piltide jaoks URL-i ja kohalike failide jaoks Base64-t