Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

A content mező formátuma: egyszerű szöveg és objektumtömb

3. lecke 12 közül Frissítve 2026. július 30. Fejlesztő
Ezen az oldalon
  1. A content mező két formátuma
  2. Szöveges formátum: a leggyakoribb eset
  3. Tömbös formátum: multimodális tartalom
  4. Mikor melyik formátumot használd?
  5. Képek technikai korlátai
  6. Főbb megállapítások

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 a text tulajdonsággal
  • image_url: egy képhivatkozás az image_url tulajdonsá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_url objektumokkal

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 content mező elfogad egyszerű szöveget (szöveg) vagy objektumtömböt (multimodális)
  • A tömbös formátum egy type mezővel rendelkező objektumokat használ: "text" vagy "image_url"
  • A detail paramé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