Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Formát obsahu: jednoduchý řetězec a pole objektů

Lekce 3 z 12 Aktualizováno 30. července 2026 Vývojář
Na této stránce
  1. Dva formáty pro pole content
  2. Formát řetězce: nejčastější případ
  3. Formát pole: multimodální obsah
  4. Kdy který formát použít?
  5. Technická omezení pro obrázky
  6. Klíčové poznatky

Dva formáty pro pole content

Pole content každé zprávy přijímá v API xAI Chat Completions dva různé formáty. Volba závisí na tom, co modelu posíláš: čistý text nebo multimodální obsah (text + obrázky).

Formát řetězce: nejčastější případ

U zpráv obsahujících pouze text je pole content jednoduchý řetězec:

{
  "role": "user",
  "content": "Explain how a transformer works."
}

Tento formát použiješ ve velké většině případů. Je jednoduchý, čitelný a pro všechny textové interakce s modelem Grok zcela postačující.

Pro zprávu system se téměř vždy používá formát řetězce:

{
  "role": "system",
  "content": "You are a software architecture expert. Respond in English with Python code examples."
}

Formát pole: multimodální obsah

Pokud potřebuješ spolu s textem odeslat obrázky, stane se z pole content pole typovaných objektů. Každý objekt obsahuje pole type, které určuje jeho povahu.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What does this image show?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

Dostupné typy objektů

Pole obsahu přijímá dva typy objektů:

  • text: textový blok s vlastností text
  • image_url: odkaz na obrázek s vlastností image_url

Do jedné zprávy můžeš kombinovat libovolný počet objektů. Například pokud chceš, aby model porovnal dva obrázky:

{
  "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"}}
  ]
}

Parametr detail pro obrázky

Každý objekt image_url přijímá volitelný parametr detail, který řídí rozlišení analýzy:

  • auto: model automaticky zvolí úroveň detailu (výchozí hodnota)
  • low: rychlá a úsporná analýza, postačující pro jednoduché obrázky (ikony, základní diagramy)
  • high: podrobná analýza, doporučená pro složité obrázky (dokumenty, fotografie, rozhraní)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Volba úrovně detailu přímo ovlivňuje počet spotřebovaných tokenů, a tedy i cenu požadavku.

Kdy který formát použít?

Pravidlo je jednoduché:

  • Pouze text → formát řetězce (jednodušší, čitelnější)
  • Text + obrázky → formát pole (nutné pro multimodální obsah)
  • Pouze obrázky → formát pole obsahující pouze objekty image_url

Formát pole s jediným objektem text je funkčně ekvivalentní formátu řetězce, ale zbytečně upovídaný:

// Ekvivalentní, ale zbytečně složité
{"content": [{"type": "text", "text": "Hello"}]}

// Upřednostni tuto formu
{"content": "Hello"}

Technická omezení pro obrázky

Než odešleš obrázky do API xAI, měj na paměti tato omezení:

  • Maximální velikost: 20 MiB na obrázek
  • Podporované formáty: pouze JPG, JPEG, PNG (žádné GIF, WebP ani SVG)
  • Počet: žádný limit na počet obrázků na žádost
  • Kompatibilní modely: pouze grok-4.5 a vyšší

Obrázky lze poskytnout prostřednictvím veřejné URL nebo zakódované v base64 přímo v URL (formát data:image/jpeg;base64,...).

Klíčové poznatky

  • Pole content přijímá jednoduchý řetězec (text) nebo pole objektů (multimodální obsah)
  • Formát pole používá objekty s polem type: "text" nebo "image_url"
  • Parametr detail (auto, low, high) řídí rozlišení analýzy pro obrázky
  • Obrázky jsou omezeny na 20 MiB ve formátech JPG/PNG a vyžadují model grok-4.5 nebo vyšší
  • Při odesílání pouze textu použij formát řetězce – je čitelnější a jednodušší