Formát obsahu: jednoduchý reťazec a pole objektov
Na tejto strane
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ťoutextimage_url: odkaz na obrázok s vlastnosťouimage_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
contentprijí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ší