Oblika vsebine: preprost niz in polje objektov
Na tej strani
Dve obliki polja content
Polje content vsakega sporočila v API-ju xAI Chat Completions sprejema dve različni obliki. Izbira je odvisna od tega, kaj pošiljaš modelu: golo besedilo ali večpredstavnostno vsebino (besedilo + slike).
Oblika niza: najpogostejši primer
Za sporočila, ki vsebujejo izključno besedilo, je polje content preprost niz:
{
"role": "user",
"content": "Explain how a transformer works."
}
To je oblika, ki jo boš uporabljal v veliki večini primerov. Preprosta je, berljiva in zadostuje za vse besedilne interakcije z Grokom.
Za sporočilo system se skoraj vedno uporablja oblika niza:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Oblika polja: večpredstavnostna vsebina
Ko moraš poleg besedila poslati še slike, polje content postane polje tipiziranih objektov. Vsak objekt ima polje type, ki označuje njegovo naravo.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Razpoložljive vrste objektov
Polje vsebine sprejema dve vrsti objektov:
text: besedilni blok z lastnostjotextimage_url: sklic na sliko z lastnostjoimage_url
V enem sporočilu lahko združiš poljubno število objektov. Na primer, če želiš od modela zahtevati primerjavo dveh slik:
{
"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"}}
]
}
Parameter detail za slike
Vsak objekt image_url sprejme izbirni parameter detail, ki nadzira ločljivost analize:
auto: model samodejno izbere raven podrobnosti (privzeta vrednost)low: hitra in varčna analiza, zadostna za preproste slike (ikone, osnovni diagrami)high: podrobna analiza, priporočljiva za kompleksne slike (dokumenti, fotografije, vmesniki)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Izbira ravni podrobnosti neposredno vpliva na število porabljenih žetonov in s tem na strošek zahteve.
Kdaj uporabiti katero obliko?
Pravilo je preprosto:
- Samo besedilo → oblika niza (preprostejša, bolj berljiva)
- Besedilo + slike → oblika polja (obvezna za večpredstavnost)
- Samo slike → oblika polja zgolj z objekti
image_url
Oblika polja z enim samim objektom text je funkcionalno enakovredna obliki niza, vendar nepotrebno razgovorna:
// Enakovredno, a nepotrebno zapleteno
{"content": [{"type": "text", "text": "Hello"}]}
// Raje uporabi to obliko
{"content": "Hello"}
Tehnične omejitve za slike
Preden pošlješ slike v API xAI, imej v mislih naslednje omejitve:
- Največja velikost: 20 MiB na sliko
- Podprti formati: samo JPG, JPEG, PNG (brez GIF, WebP ali SVG)
- Število: ni omejitve glede števila slik na zahtevo
- Združljivi modeli: samo grok-4.5 in novejši
Slike lahko priskrbiš prek javnega URL-ja ali pa jih v samem URL-ju kodiraš v base64 (oblika data:image/jpeg;base64,...).
Ključne ugotovitve
- Polje
contentsprejema preprost niz (besedilo) ali polje objektov (večpredstavnost) - Oblika polja uporablja objekte s poljem
type:"text"ali"image_url" - Parameter
detail(auto,low,high) nadzira ločljivost analize za slike - Slike so omejene na 20 MiB v formatih JPG/PNG in zahtevajo grok-4.5 ali novejšega
- Ko pošiljaš samo besedilo, uporabi obliko niza – bolj berljiva in preprostejša je