Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Formát obsahu: jednoduchý reťazec a pole objektov

Lekcia 3 z 12 Aktualizované 30. júla 2026 Vývojár
Na tejto strane
  1. Dva formáty pre pole content
  2. Formát reťazca: najbežnejší prípad
  3. Formát poľa: multimodálny obsah
  4. Kedy použiť ktorý formát?
  5. Technické obmedzenia pre obrázky
  6. Kľúčové poznatky

Dva formáty pre pole content

Pole content každej správy prijíma v API xAI Chat Completions dva rôzne formáty. Výber závisí od toho, čo modelu odosielaš: čistý text alebo multimodálny obsah (text + obrázky).

Formát reťazca: najbežnejší prípad

Pre čisto textové správy je pole content jednoduchý reťazec:

{
  "role": "user",
  "content": "Vysvetli, ako funguje transformer."
}

Toto je formát, ktorý použiješ vo veľkej väčšine prípadov. Je jednoduchý, čitateľný a postačuje na všetky textové interakcie s modelom Grok.

Pre správu system sa takmer vždy používa formát reťazca:

{
  "role": "system",
  "content": "Si expert na softvérovú architektúru. Odpovedaj v angličtine s príkladmi kódu v Pythone."
}

Formát poľa: multimodálny obsah

Keď potrebuješ odoslať obrázky spolu s textom, pole content sa stane poľom typovaných objektov. Každý objekt má pole type, ktoré určuje jeho povahu.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Čo zobrazuje tento obrázok?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

Dostupné typy objektov

Pole obsahu prijíma dva typy objektov:

  • text: textový blok s vlastnosťou text
  • image_url: odkaz na obrázok s vlastnosťou image_url

V jednej správe môžeš kombinovať ľubovoľný počet objektov. Napríklad, ak chceš požiadať model o porovnanie dvoch obrázkov:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Porovnaj tieto dva diagramy architektúry."},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
  ]
}

Parameter detail pre obrázky

Každý objekt image_url prijíma voliteľný parameter detail, ktorý riadi rozlíšenie analýzy:

  • auto: model automaticky zvolí úroveň detailu (predvolená hodnota)
  • low: rýchla a úsporná analýza, postačujúca pre jednoduché obrázky (ikony, základné diagramy)
  • high: podrobná analýza, odporúčaná pre zložité obrázky (dokumenty, fotografie, rozhrania)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Voľba úrovne detailu priamo ovplyvňuje počet spotrebovaných tokenov, a teda aj cenu požiadavky.

Kedy použiť ktorý formát?

Pravidlo je jednoduché:

  • Iba text → formát reťazca (jednoduchší, čitateľnejší)
  • Text + obrázky → formát poľa (povinné pre multimodálne vstupy)
  • Iba obrázky → formát poľa iba s objektmi image_url

Formát poľa s jediným objektom text je funkčne ekvivalentný formátu reťazca, ale zbytočne rozvláčný:

// Ekvivalentné, ale zbytočne zložité
{"content": [{"type": "text", "text": "Ahoj"}]}

// Uprednostni tento tvar
{"content": "Ahoj"}

Technické obmedzenia pre obrázky

Pred odoslaním obrázkov do API xAI maj na pamäti tieto limity:

  • Maximálna veľkosť: 20 MiB na obrázok
  • Podporované formáty: iba JPG, JPEG, PNG (žiadne GIF, WebP ani SVG)
  • Počet: žiadny limit na počet obrázkov na požiadavku
  • Kompatibilné modely: iba grok-4.5 a vyššie

Obrázky môžu byť poskytnuté cez verejnú URL alebo zakódované v base64 priamo v URL (formát data:image/jpeg;base64,...).

Kľúčové poznatky

  • Pole content prijíma jednoduchý reťazec (text) alebo pole objektov (multimodálne)
  • Formát poľa používa objekty s poľom type: "text" alebo "image_url"
  • Parameter detail (auto, low, high) riadi rozlíšenie analýzy pre obrázky
  • Obrázky sú obmedzené na 20 MiB vo formáte JPG/PNG a vyžadujú model grok-4.5 alebo vyšší
  • Pri odosielaní iba textu používaj formát reťazca – je čitateľnejší a jednoduchší