Formatul conținutului: șir simplu și tablou de obiecte
Pe această pagină
Două formate pentru câmpul content
Câmpul content al fiecărui mesaj acceptă două formate diferite în API-ul xAI Chat Completions. Alegerea depinde de ceea ce trimiteți modelului: text simplu sau conținut multimodal (text + imagini).
Formatul șir: cazul cel mai frecvent
Pentru mesajele care conțin exclusiv text, câmpul content este un șir simplu:
{
"role": "user",
"content": "Explain how a transformer works."
}
Acesta este formatul pe care îl veți utiliza în marea majoritate a cazurilor. Este simplu, lizibil și suficient pentru toate interacțiunile textuale cu Grok.
Pentru mesajul system, se utilizează aproape întotdeauna formatul șir:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Formatul tablou: conținut multimodal
Atunci când trebuie să trimiteți imagini împreună cu text, câmpul content devine un tablou de obiecte tipizate. Fiecare obiect posedă un câmp type care îi indică natura.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Tipurile de obiecte disponibile
Tabloul de conținut acceptă două tipuri de obiecte:
text: un bloc de text cu proprietateatextimage_url: o referință către o imagine cu proprietateaimage_url
Puteți combina câte obiecte doriți într-un singur mesaj. De exemplu, pentru a cere modelului să compare două imagini:
{
"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"}}
]
}
Parametrul detail pentru imagini
Fiecare obiect image_url acceptă un parametru opțional detail care controlează rezoluția analizei:
auto: modelul alege automat nivelul de detaliu (valoarea implicită)low: analiză rapidă și economică, suficientă pentru imagini simple (pictograme, diagrame de bază)high: analiză detaliată, recomandată pentru imagini complexe (documente, fotografii, interfețe)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Alegerea nivelului de detaliu impactează direct numărul de tokeni consumați și, prin urmare, costul cererii.
Când să utilizați fiecare format?
Regula este simplă:
- Doar text → format șir (mai simplu, mai lizibil)
- Text + imagini → format tablou (obligatoriu pentru multimodal)
- Doar imagini → format tablou cu obiecte exclusiv de tip
image_url
Un format tablou care conține un singur obiect text este funcțional echivalent cu formatul șir, dar inutil de verbose:
// Echivalent, dar inutil de complex
{"content": [{"type": "text", "text": "Hello"}]}
// Preferați această formă
{"content": "Hello"}
Constrângeri tehnice pentru imagini
Înainte de a trimite imagini către API-ul xAI, rețineți următoarele limite:
- Dimensiune maximă: 20 MiB per imagine
- Formate acceptate: doar JPG, JPEG, PNG (fără GIF, WebP sau SVG)
- Număr: nicio limită privind numărul de imagini per cerere
- Modele compatibile: doar grok-4.5 și versiunile superioare
Imaginile pot fi furnizate printr-un URL public sau codificate în base64 direct în URL (format data:image/jpeg;base64,...).
Puncte cheie
- Câmpul
contentacceptă un șir simplu (text) sau un tablou de obiecte (multimodal) - Formatul tablou utilizează obiecte cu un câmp
type:"text"sau"image_url" - Parametrul
detail(auto,low,high) controlează rezoluția analizei pentru imagini - Imaginile sunt limitate la 20 MiB în format JPG/PNG și necesită grok-4.5 sau o versiune superioară
- Utilizați formatul șir atunci când trimiteți doar text – este mai lizibil și mai simplu