Премини към основното съдържание
Български— Изберете език
Меню

Формат на съдържанието: обикновен низ и масив от обекти

Урок 3 от 12 Обновен 30 юли 2026 г. Програмист
На тази страница
  1. Два формата за полето content
  2. Формат низ: най-честият случай
  3. Формат масив: мултимодално съдържание
  4. Кога кой формат да използвате?
  5. Технически ограничения за изображения
  6. Ключови изводи

Два формата за полето 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: текстов блок със свойството text
  • image_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 или по-нова версия
  • Използвайте формата низ, когато изпращате само текст – той е по-четим и по-прост