Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Oblika vsebine: preprost niz in polje objektov

Lekcija 3 od 12 Posodobljeno 30. julij 2026 Razvijalec
Na tej strani
  1. Dve obliki polja content
  2. Oblika niza: najpogostejši primer
  3. Oblika polja: večpredstavnostna vsebina
  4. Kdaj uporabiti katero obliko?
  5. Tehnične omejitve za slike
  6. Ključne ugotovitve

Dve obliki polja content

Polje content vsakega sporočila v API-ju xAI Chat Completions sprejema dve različni obliki. Izbira je odvisna od tega, kaj pošiljaš modelu: golo besedilo ali večpredstavnostno vsebino (besedilo + slike).

Oblika niza: najpogostejši primer

Za sporočila, ki vsebujejo izključno besedilo, je polje content preprost niz:

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

To je oblika, ki jo boš uporabljal v veliki večini primerov. Preprosta je, berljiva in zadostuje za vse besedilne interakcije z Grokom.

Za sporočilo system se skoraj vedno uporablja oblika niza:

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

Oblika polja: večpredstavnostna vsebina

Ko moraš poleg besedila poslati še slike, polje content postane polje tipiziranih objektov. Vsak objekt ima polje type, ki označuje njegovo naravo.

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

Razpoložljive vrste objektov

Polje vsebine sprejema dve vrsti objektov:

  • text: besedilni blok z lastnostjo text
  • image_url: sklic na sliko z lastnostjo image_url

V enem sporočilu lahko združiš poljubno število objektov. Na primer, če želiš od modela zahtevati primerjavo dveh slik:

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

Parameter detail za slike

Vsak objekt image_url sprejme izbirni parameter detail, ki nadzira ločljivost analize:

  • auto: model samodejno izbere raven podrobnosti (privzeta vrednost)
  • low: hitra in varčna analiza, zadostna za preproste slike (ikone, osnovni diagrami)
  • high: podrobna analiza, priporočljiva za kompleksne slike (dokumenti, fotografije, vmesniki)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Izbira ravni podrobnosti neposredno vpliva na število porabljenih žetonov in s tem na strošek zahteve.

Kdaj uporabiti katero obliko?

Pravilo je preprosto:

  • Samo besedilo → oblika niza (preprostejša, bolj berljiva)
  • Besedilo + slike → oblika polja (obvezna za večpredstavnost)
  • Samo slike → oblika polja zgolj z objekti image_url

Oblika polja z enim samim objektom text je funkcionalno enakovredna obliki niza, vendar nepotrebno razgovorna:

// Enakovredno, a nepotrebno zapleteno
{"content": [{"type": "text", "text": "Hello"}]}

// Raje uporabi to obliko
{"content": "Hello"}

Tehnične omejitve za slike

Preden pošlješ slike v API xAI, imej v mislih naslednje omejitve:

  • Največja velikost: 20 MiB na sliko
  • Podprti formati: samo JPG, JPEG, PNG (brez GIF, WebP ali SVG)
  • Število: ni omejitve glede števila slik na zahtevo
  • Združljivi modeli: samo grok-4.5 in novejši

Slike lahko priskrbiš prek javnega URL-ja ali pa jih v samem URL-ju kodiraš v base64 (oblika data:image/jpeg;base64,...).

Ključne ugotovitve

  • Polje content sprejema preprost niz (besedilo) ali polje objektov (večpredstavnost)
  • Oblika polja uporablja objekte s poljem type: "text" ali "image_url"
  • Parameter detail (auto, low, high) nadzira ločljivost analize za slike
  • Slike so omejene na 20 MiB v formatih JPG/PNG in zahtevajo grok-4.5 ali novejšega
  • Ko pošiljaš samo besedilo, uporabi obliko niza – bolj berljiva in preprostejša je