Turinio formatas: paprasta eilutė ir objektų masyvas
Šiame puslapyje
Du turinio lauko formatai
xAI „Chat Completions“ API kiekvieno pranešimo content laukas priima du skirtingus formatus. Pasirinkimas priklauso nuo to, ką siunči modeliui: gryną tekstą ar multimedinį turinį (tekstas + paveikslėliai).
Eilutės formatas: dažniausias atvejis
Grynai tekstiniams pranešimams content laukas yra paprasta eilutė:
{
"role": "user",
"content": "Explain how a transformer works."
}
Tai formatas, kurį naudosite absoliučia dauguma atvejų. Jis paprastas, skaitomas ir pakankamas visiems tekstiniams ryšiams su Grok.
system pranešimui beveik visada naudojamas eilutės formatas:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Masyvo formatas: multimedinis turinys
Kai kartu su tekstu reikia siųsti paveikslėlius, content laukas tampa tipizuotų objektų masyvu. Kiekvienas objektas turi type lauką, nurodantį jo pobūdį.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Galimi objektų tipai
Turinio masyvas priima dviejų tipų objektus:
text: teksto blokas sutextsavybeimage_url: nuoroda į paveikslėlį suimage_urlsavybe
Viename pranešime gali derinti tiek objektų, kiek reikia. Pavyzdžiui, jei nori paprašyti modelio palyginti du paveikslėlius:
{
"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"}}
]
}
Paveikslėlių detail parametras
Kiekvienas image_url objektas priima nebūtiną detail parametrą, kuris valdo analizės skiriamąją gebą:
auto: modelis automatiškai pasirenka detalumo lygį (numatytoji reikšmė)low: greita ir ekonomiška analizė, pakankama paprastiems paveikslėliams (piktogramoms, pagrindinėms schemoms)high: išsami analizė, rekomenduojama sudėtingiems paveikslėliams (dokumentams, nuotraukoms, sąsajoms)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Detalumo lygio pasirinkimas tiesiogiai veikia sunaudojamų žetonų skaičių, taigi ir užklausos kainą.
Kada naudoti kurį formatą?
Taisyklė paprasta:
- Tik tekstas → eilutės formatas (paprastesnis, skaitomesnis)
- Tekstas + paveikslėliai → masyvo formatas (būtinas multimediniam turiniui)
- Tik paveikslėliai → masyvo formatas tik su
image_urlobjektais
Masyvo formatas su vienu text objektu funkciškai lygiavertis eilutės formatui, bet be reikalo išplėstas:
// Ekvivalentu, bet be reikalo sudėtinga
{"content": [{"type": "text", "text": "Hello"}]}
// Geriau rinktis šią formą
{"content": "Hello"}
Techniniai apribojimai paveikslėliams
Prieš siųsdamas paveikslėlius xAI API, atsižvelk į šiuos limitus:
- Maksimalus dydis: 20 MiB vienam paveikslėliui
- Priimami formatai: tik JPG, JPEG, PNG (jokių GIF, WebP ar SVG)
- Skaičius: joks limitas paveikslėlių skaičiui vienoje užklausoje
- Suderinami modeliai: tik grok-4.5 ir naujesni
Paveikslėlius galima pateikti naudojant viešą URL arba užkoduojant juos base64 formatu tiesiai URL eilutėje (formatas data:image/jpeg;base64,...).
Svarbiausi punktai
contentlaukas priima paprastą eilutę (tekstui) arba objektų masyvą (multimediniam turiniui)- Masyvo formatas naudoja objektus su
typelauku:"text"arba"image_url" detailparametras (auto,low,high) valdo paveikslėlių analizės skiriamąją gebą- Paveikslėlių dydis ribojamas iki 20 MiB (JPG/PNG formatu), ir jiems reikia grok-4.5 arba naujesnio modelio
- Siųsdamas tik tekstą, naudok eilutės formatą – jis skaitomesnis ir paprastesnis