Formáty obrázkov: URL a Base64
Na tejto strane
Aktualizované 3. novembra 2026. Pri používaní Responses API sa objekty
input_imageainput_textumiestňujú do poľacontentsprávy{"role": "user", ...}, nie priamo doinput. Pôvodný príklad v Pythone volal metóduclient.responses.create()na klientovixai-sdk, ktorá neexistuje, a obsahoval API kľúč priamo v kóde: teraz používa funkcieuser(...)aimage(...)z SDK, pričom kľúč sa číta z premenných prostredia. Pridané upozornenie xAI na ukladanie histórie. Kód overený s verziouxai-sdk1.21.0. Zdroj: Image Understanding.
Odosielanie obrázkov modelu Grok
Modely Grok od verzie grok-4.5 vyššie zahŕňajú schopnosti počítačového videnia. Do svojich požiadaviek API môžeš odoslať jeden alebo viacero obrázkov a model ich analyzuje, aby odpovedal na tvoje otázky. Tomuto procesu sa hovorí pochopenie obrazu alebo multimodálne videnie.
Predtým, než sa ponoríš do konkrétnych prípadov použitia, je nevyhnutné osvojiť si dva formáty odovzdávania obrázkov, ktoré podporuje API xAI.
Priame URL
Najjednoduchšou metódou je poskytnutie verejnej URL adresy obrázka. Model si ho automaticky stiahne a analyzuje.
Pri používaní Responses API (hlavný koncový bod):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Podrobne opíš tento obrázok."
}
]
}
]
}
xAI odporúča, aby si pri odosielaní obrázkov neukladal históriu požiadaviek a odpovedí na ich serveroch, inak môže požiadavka zlyhať: pri Responses API pridaj parameter "store": false.
Pri používaní Chat Completions API (staršie, kompatibilné s OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Podrobne opíš tento obrázok."
}
]
}
]
}
URL adresa musí smerovať na verejne dostupný súbor s obrázkom. Ak je obrázok chránený overením alebo sa nachádza za chránenou CDN, použij namiesto toho formát Base64.
Kódovanie Base64 (Data URI)
Druhý formát spočíva v zakódovaní obrázka priamo do požiadavky ako reťazca Base64 s predponou MIME typu. Toto je ideálna metóda pri práci s lokálnymi obrázkami, snímkami obrazovky alebo dynamicky generovanými súbormi.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
Predpona data:image/jpeg;base64, informuje model o MIME type obrázka. Uprav ju podľa formátu:
data:image/jpeg;base64,pre súbory JPG/JPEGdata:image/png;base64,pre súbory PNG
Kódovanie obrázka v Pythone
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}"
Kódovanie v JavaScripte/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Kľúčové rozdiely medzi URL a Base64
| Kritérium | URL | Base64 |
|---|---|---|
| Veľkosť požiadavky | Ľahká (len URL) | Ťažká (+33 % oproti pôvodnému súboru) |
| Prístupnosť | Vyžaduje sa verejný obrázok | Funguje s akýmkoľvek lokálnym súborom |
| Latencia | Sťahovanie serverom | Dáta priamo v požiadavke |
| Typický prípad použitia | Webové obrázky, CDN, cloudové úložisko | Lokálne súbory, snímky obrazovky, nahrávania |
Kombinovanie textu a obrázkov
Pole content správy akceptuje zmiešané pole objektov input_image a input_text v ľubovoľnom poradí: text a obrázky môžeš voľne striedať. Pri použití natívneho SDK xAI sa rovnaká správa zostavuje pomocou funkcie user(), ktorá akceptuje text a obrázky vytvorené funkciou image() v postupnosti:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # kľúč sa číta z XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Porovnaj tieto dve fotky:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"Aké sú hlavné rozdiely?",
)
)
response = chat.sample()
print(response.content)
Funkcia image() akceptuje verejnú URL adresu alebo Data URI v formáte Base64.
Kľúčové poznatky
- Podporované sú dva formáty obrázkov: Priame URL a Base64 (Data URI)
- Akceptované sú iba formáty JPG, JPEG a PNG
- Každý obrázok nesmie presiahnuť 20 MiB
- Počet obrázkov na jednu požiadavku je neobmedzený
- Responses API umiestňuje
input_imagedo poľacontentsprávy; Chat Completions používa častiimage_url; SDK xAI používaimage()vnútriuser() - Pre verejné obrázky uprednostni URL, pre lokálne súbory použij Base64