A content mező formátuma: egyszerű szöveg és objektumtömb
Ezen az oldalon
A content mező két formátuma
Az xAI Chat Completions API-ban minden üzenet content mezője két különböző formátumot fogad el. A választás attól függ, mit küldesz a modellnek: egyszerű szöveget vagy multimodális tartalmat (szöveg + képek).
Szöveges formátum: a leggyakoribb eset
Kizárólag szöveges üzenetek esetén a content mező egy egyszerű szöveg (string):
{
"role": "user",
"content": "Magyarázd el, hogyan működik egy transzformer."
}
Ezt a formátumot az esetek túlnyomó többségében használod majd. Egyszerű, olvasható, és minden szöveges Grok-kal folytatott interakcióhoz elegendő.
A system üzeneteknél szinte mindig a szöveges formátumot alkalmazzák:
{
"role": "system",
"content": "Te egy szoftverarchitektúra-szakértő vagy. Angolul válaszolj, Python kódpéldákkal."
}
Tömbös formátum: multimodális tartalom
Ha szöveg mellett képeket is küldenéd, a content mező típusozott objektumok tömbjévé válik. Minden objektum rendelkezik egy type mezővel, amely jelzi a természetét.
{
"role": "user",
"content": [
{
"type": "text",
"text": "Mit mutat ez a kép?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Elérhető objektumtípusok
A tartalomtömb két objektumtípust fogad el:
text: egy szövegblokk atexttulajdonsággalimage_url: egy képhivatkozás azimage_urltulajdonsággal
Egyetlen üzeneten belül tetszőleges számú objektumot kombinálhatsz. Például, ha arra kéred a modellt, hogy hasonlítson össze két képet:
{
"role": "user",
"content": [
{"type": "text", "text": "Hasonlítsd össze ezt a két architektúra-diagramot."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
A képek detail paramétere
Minden image_url objektum elfogad egy opcionális detail paramétert, amely szabályozza az elemzés felbontását:
auto: a modell automatikusan választja ki a részletességi szintet (alapértelmezett érték)low: gyors és gazdaságos elemzés, egyszerű képekhez elegendő (ikonok, alapvető diagramok)high: részletes elemzés, összetett képekhez ajánlott (dokumentumok, fényképek, felületek)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
A részletességi szint megválasztása közvetlenül befolyásolja a felhasznált tokenek számát, és ezáltal a kérés költségét is.
Mikor melyik formátumot használd?
A szabály egyszerű:
- Csak szöveg → szöveges formátum (egyszerűbb, olvashatóbb)
- Szöveg + képek → tömbös formátum (multimodális esetben kötelező)
- Csak képek → tömbös formátum, kizárólag
image_urlobjektumokkal
Egyetlen text objektumot tartalmazó tömbös formátum funkcionálisan egyenértékű a szöveges formátummal, de feleslegesen bőbeszédű:
// Egyenértékű, de feleslegesen bonyolult
{"content": [{"type": "text", "text": "Szia"}]}
// Ezt a formát érdemes preferálni
{"content": "Szia"}
Képek technikai korlátai
Mielőtt képeket küldenél az xAI API-nak, tartsd észben ezeket a korlátokat:
- Maximális méret: képenként 20 MiB
- Elfogadott formátumok: kizárólag JPG, JPEG, PNG (nincs GIF, WebP vagy SVG)
- Darabszám: nincs korlátozás a kérésenkénti képek számára
- Kompatibilis modellek: kizárólag grok-4.5 és újabb verziók
A képeket nyilvános URL-címen keresztül vagy közvetlenül az URL-be ágyazott base64 kódolással is megadhatod (data:image/jpeg;base64,... formátumban).
Főbb megállapítások
- A
contentmező elfogad egyszerű szöveget (szöveg) vagy objektumtömböt (multimodális) - A tömbös formátum egy
typemezővel rendelkező objektumokat használ:"text"vagy"image_url" - A
detailparaméter (auto,low,high) szabályozza a képek elemzési felbontását - A képek mérete legfeljebb 20 MiB lehet JPG/PNG formátumban, és grok-4.5 vagy újabb modellt igényelnek
- Kizárólag szöveg küldésekor használd a szöveges formátumot – ez olvashatóbb és egyszerűbb