Formát obsahu: jednoduchý řetězec a pole objektů
Na této stránce
Dva formáty pro pole content
Pole content každé zprávy přijímá v API xAI Chat Completions dva různé formáty. Volba závisí na tom, co modelu posíláš: čistý text nebo multimodální obsah (text + obrázky).
Formát řetězce: nejčastější případ
U zpráv obsahujících pouze text je pole content jednoduchý řetězec:
{
"role": "user",
"content": "Explain how a transformer works."
}
Tento formát použiješ ve velké většině případů. Je jednoduchý, čitelný a pro všechny textové interakce s modelem Grok zcela postačující.
Pro zprávu system se téměř vždy používá formát řetězce:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Formát pole: multimodální obsah
Pokud potřebuješ spolu s textem odeslat obrázky, stane se z pole content pole typovaných objektů. Každý objekt obsahuje pole type, které určuje jeho povahu.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Dostupné typy objektů
Pole obsahu přijímá dva typy objektů:
text: textový blok s vlastnostítextimage_url: odkaz na obrázek s vlastnostíimage_url
Do jedné zprávy můžeš kombinovat libovolný počet objektů. Například pokud chceš, aby model porovnal dva obrázky:
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two architecture diagrams."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
Parametr detail pro obrázky
Každý objekt image_url přijímá volitelný parametr detail, který řídí rozlišení analýzy:
auto: model automaticky zvolí úroveň detailu (výchozí hodnota)low: rychlá a úsporná analýza, postačující pro jednoduché obrázky (ikony, základní diagramy)high: podrobná analýza, doporučená pro složité obrázky (dokumenty, fotografie, rozhraní)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Volba úrovně detailu přímo ovlivňuje počet spotřebovaných tokenů, a tedy i cenu požadavku.
Kdy který formát použít?
Pravidlo je jednoduché:
- Pouze text → formát řetězce (jednodušší, čitelnější)
- Text + obrázky → formát pole (nutné pro multimodální obsah)
- Pouze obrázky → formát pole obsahující pouze objekty
image_url
Formát pole s jediným objektem text je funkčně ekvivalentní formátu řetězce, ale zbytečně upovídaný:
// Ekvivalentní, ale zbytečně složité
{"content": [{"type": "text", "text": "Hello"}]}
// Upřednostni tuto formu
{"content": "Hello"}
Technická omezení pro obrázky
Než odešleš obrázky do API xAI, měj na paměti tato omezení:
- Maximální velikost: 20 MiB na obrázek
- Podporované formáty: pouze JPG, JPEG, PNG (žádné GIF, WebP ani SVG)
- Počet: žádný limit na počet obrázků na žádost
- Kompatibilní modely: pouze grok-4.5 a vyšší
Obrázky lze poskytnout prostřednictvím veřejné URL nebo zakódované v base64 přímo v URL (formát data:image/jpeg;base64,...).
Klíčové poznatky
- Pole
contentpřijímá jednoduchý řetězec (text) nebo pole objektů (multimodální obsah) - Formát pole používá objekty s polem
type:"text"nebo"image_url" - Parametr
detail(auto,low,high) řídí rozlišení analýzy pro obrázky - Obrázky jsou omezeny na 20 MiB ve formátech JPG/PNG a vyžadují model grok-4.5 nebo vyšší
- Při odesílání pouze textu použij formát řetězce – je čitelnější a jednodušší