Formāts saturam: vienkārša virkne un objektu masīvs
Šajā lapā
Divi formāti laukam content
Katra ziņojuma lauks content xAI Chat Completions API pieņem divus dažādus formātus. Izvēle ir atkarīga no tā, ko nosūti modelim: tikai tekstu vai multimodālu saturu (teksts + attēli).
Virknes formāts: visizplatītākais gadījums
Tīri tekstveida ziņojumiem lauks content ir vienkārša virkne:
{
"role": "user",
"content": "Explain how a transformer works."
}
Šo formātu izmantosi lielākajā daļā gadījumu. Tas ir vienkāršs, lasāms un pietiekams visām teksta mijiedarbībām ar Grok.
Ziņojumam ar lomu system gandrīz vienmēr tiek izmantots virknes formāts:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Masīva formāts: multimodāls saturs
Ja kopā ar tekstu ir jānosūta attēli, lauks content kļūst par tipētu objektu masīvu. Katram objektam ir lauks type, kas norāda tā veidu.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Pieejamie objektu veidi
Satura masīvs pieņem divu veidu objektus:
text: teksta bloks ar īpašībutextimage_url: atsauce uz attēlu ar īpašībuimage_url
Vienā ziņojumā vari apvienot tik daudz objektu, cik nepieciešams. Piemēram, lai lūgtu modelim salīdzināt divus attēlus:
{
"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"}}
]
}
Parametrs detail attēliem
Katrs image_url objekts pieņem neobligātu parametru detail, kas kontrolē analīzes izšķirtspēju:
auto: modelis automātiski izvēlas detalizācijas līmeni (noklusējuma vērtība)low: ātra un ekonomiska analīze, kas pietiekama vienkāršiem attēliem (ikonām, pamata diagrammām)high: detalizēta analīze, ieteicama sarežģītiem attēliem (dokumentiem, fotogrāfijām, saskarnēm)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Detalizācijas līmeņa izvēle tieši ietekmē patērēto tokeno skaitu un līdz ar to arī pieprasījuma izmaksas.
Kad lietot kurus formātus?
Noteikums ir vienkāršs:
- Tikai teksts → virknes formāts (vienkāršāks, lasāmāks)
- Teksts + attēli → masīva formāts (nepieciešams multimodālam saturam)
- Tikai attēli → masīva formāts, kurā ir tikai
image_urlobjekti
Masīva formāts ar vienu text objektu funkcionāli ir līdzvērtīgs virknes formātam, taču tas ir lieki daudzvārdīgs:
// Līdzvērtīgi, bet nevajadzīgi sarežģīti
{"content": [{"type": "text", "text": "Hello"}]}
// Dod priekšroku šai formai
{"content": "Hello"}
Tehniskie ierobežojumi attēliem
Pirms attēlu nosūtīšanas uz xAI API, ņem vērā šos ierobežojumus:
- Maksimālais izmērs: 20 MiB vienam attēlam
- Pieņemtie formāti: tikai JPG, JPEG, PNG (nav GIF, WebP vai SVG)
- Skaits: nav ierobežojumu attēlu skaitam vienā pieprasījumā
- Saderīgie modeļi: tikai grok-4.5 un jaunākas versijas
Attēlus var norādīt, izmantojot publisku URL, vai kodēt base64 formātā tieši URL iekšienē (formāts data:image/jpeg;base64,...).
Galvenās atziņas
- Lauks
contentpieņem vienkāršu virkni (teksts) vai objektu masīvu (multimodāls saturs) - Masīva formāts izmanto objektus ar lauku
type:"text"vai"image_url" - Parametrs
detail(auto,low,high) kontrolē attēlu analīzes izšķirtspēju - Attēliem ir 20 MiB lieluma ierobežojums JPG/PNG formātā, un tie prasa grok-4.5 vai jaunāku versiju
- Izmanto virknes formātu, ja nosūti tikai tekstu – tas ir lasāmāks un vienkāršāks