Формат на съдържанието: обикновен низ и масив от обекти
На тази страница
Два формата за полето content
Полето content на всяко съобщение приема два различни формата в API за Chat Completions на xAI. Изборът зависи от това какво изпращате на модела: чист текст или мултимодално съдържание (текст + изображения).
Формат низ: най-честият случай
За съобщения, съдържащи единствено текст, полето content е обикновен низ:
{
"role": "user",
"content": "Explain how a transformer works."
}
Това е форматът, който ще използвате в огромното мнозинство от случаите. Той е прост, четим и напълно достатъчен за всички текстови взаимодействия с Grok.
За съобщението system почти винаги се използва форматът низ:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Формат масив: мултимодално съдържание
Когато трябва да изпратите изображения заедно с текст, полето content се превръща в масив от типизирани обекти. Всеки обект има поле type, което указва неговата природа.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Налични типове обекти
Масивът за съдържание приема два типа обекти:
text: текстов блок със свойствотоtextimage_url: референция към изображение със свойствотоimage_url
Можете да комбинирате толкова обекти, колкото е необходимо в рамките на едно съобщение. Например, за да поискате от модела да сравни две изображения:
{
"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"}}
]
}
Параметърът detail за изображения
Всеки обект image_url приема незадължителен параметър detail, който контролира резолюцията на анализа:
auto: моделът автоматично избира нивото на детайлност (стойност по подразбиране)low: бърз и икономичен анализ, достатъчен за прости изображения (икони, основни диаграми)high: детайлен анализ, препоръчителен за сложни изображения (документи, фотографии, интерфейси)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Изборът на ниво на детайлност директно влияе върху броя консумирани токени и следователно върху цената на заявката.
Кога кой формат да използвате?
Правилото е просто:
- Само текст → формат низ (по-прост, по-четим)
- Текст + изображения → формат масив (задължителен за мултимодалност)
- Само изображения → формат масив само с обекти
image_url
Формат масив с един единствен обект text е функционално еквивалентен на формата низ, но излишно многословен:
// Еквивалентно, но ненужно сложно
{"content": [{"type": "text", "text": "Hello"}]}
// Предпочитайте този вид
{"content": "Hello"}
Технически ограничения за изображения
Преди да изпратите изображения към API на xAI, имайте предвид следните лимити:
- Максимален размер: 20 MiB на изображение
- Приети формати: само JPG, JPEG, PNG (без GIF, WebP или SVG)
- Брой: няма ограничение за броя изображения на заявка
- Съвместими модели: само grok-4.5 и по-нови версии
Изображенията могат да бъдат предоставени чрез публичен URL или кодирани в base64 директно в самия URL (формат data:image/jpeg;base64,...).
Ключови изводи
- Полето
contentприема обикновен низ (текст) или масив от обекти (мултимодално) - Форматът масив използва обекти с поле
type:"text"или"image_url" - Параметърът
detail(auto,low,high) контролира резолюцията на анализа за изображения - Изображенията са ограничени до 20 MiB във формати JPG/PNG и изискват grok-4.5 или по-нова версия
- Използвайте формата низ, когато изпращате само текст – той е по-четим и по-прост