Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Sisu vorming: lihtne string ja objektide massiiv

Õppetund 3 / 12 Värskendatud 30. juuli 2026 Arendajatele
Sellel lehel
  1. Kaks sisu välja vormingut
  2. Stringi vorming: kõige levinum juhtum
  3. Massiivi vorming: multimeediumsisu
  4. Millal millist vormingut kasutada?
  5. Piltide tehnilised piirangud
  6. Peamised punktid

Kaks sisu välja vormingut

IGA sõnumi content väli aktsepteerib xAI Chat Completions API-s kahte erinevat vormingut. Valik sõltub sellest, mida mudelile saadad: kas palja teksti või multimeediumsisu (tekst + pildid).

Stringi vorming: kõige levinum juhtum

Puhtalt tekstisõnumite puhul on content väli lihtne string:

{
  "role": "user",
  "content": "Selgita, kuidas transformer töötab."
}

See on vorming, mida kasutad valdaval enamikul juhtudel. See on lihtne, loetav ja piisav igasuguseks tekstisuhtluseks Grokiga.

system sõnumi puhul kasutatakse peaaegu alati stringi vormingut:

{
  "role": "system",
  "content": "Oled tarkvara arhitektuuri ekspert. Vasta inglise keeles, tuues näiteid Pythoni koodist."
}

Massiivi vorming: multimeediumsisu

Kui pead saatma koos tekstiga ka pilte, muutub content väli tüübitud objektide massiiviks. Igal objektil on väli type, mis näitab selle olemust.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Mida see pilt kujutab?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

Saadaval olevad objektitüübid

Sisu massiiv aktsepteerib kahte tüüpi objekte:

  • text: tekstiplokk omadusega text
  • image_url: viide pildile omadusega image_url

Saad ühes sõnumis kombineerida nii palju objekte, kui vaja. Näiteks, kui soovid, et mudel võrdleks kahte pilti:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Võrdle neid kahte arhitektuuri skeemi."},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
  ]
}

Piltide detaili parameeter

Iga image_url objekt aktsepteerib valikulist parameetrit detail, mis kontrollib analüüsi lahutusvõimet:

  • auto: mudel valib detailitase automaatselt (vaikimisi väärtus)
  • low: kiire ja ökonoomne analüüs, piisab lihtsate piltide jaoks (ikoonid, lihtsad skeemid)
  • high: üksikasjalik analüüs, soovitatav keerukate piltide jaoks (dokumendid, fotod, liidesed)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Detailitaseme valik mõjutab otseselt tarbitavate tokenite arvu ja seega ka päringu hinda.

Millal millist vormingut kasutada?

Reegel on lihtne:

  • Ainult tekst → stringi vorming (lihtsam, loetavam)
  • Tekst + pildid → massiivi vorming (kohustuslik multimeediumi jaoks)
  • Ainult pildid → massiivi vorming, mis sisaldab ainult image_url objekte

Massiivi vorming, mis sisaldab ühteainsat text objekti, on funktsionaalselt samaväärne stringi vorminguga, kuid on põhjendamatult sõnaohker:

// Samaväärne, kuid põhjendamatult keeruline
{"content": [{"type": "text", "text": "Tere"}]}

// Eelista seda vormi
{"content": "Tere"}

Piltide tehnilised piirangud

Enne piltide xAI API-le saatmist pea meeles järgmisi piiranguid:

  • Maksimaalne suurus: 20 MiB pildi kohta
  • Aktsepteeritud vormingud: ainult JPG, JPEG, PNG (ei GIF, WebP ega SVG)
  • Arv: piirangut piltide arvule päringu kohta ei ole
  • Ühilduvad mudelid: ainult grok-4.5 ja uuemad

Pilte saab edastada avaliku URL-i kaudu või kodeerituna base64-formaadis otse URL-i sees (vorming data:image/jpeg;base64,...).

Peamised punktid

  • Väli content aktsepteerib lihtsat stringi (tekst) või objektide massiivi (multimeedium)
  • Massiivi vorming kasutab objekte väljaga type: "text" või "image_url"
  • Parameeter detail (auto, low, high) kontrollib piltide analüüsi lahutusvõimet
  • Piltide suurus on piiratud 20 MiB-ga (JPG/PNG) ja need nõuavad mudelit grok-4.5 või uuemat
  • Kasuta ainult teksti saatmisel stringi vormingut – see on loetavam ja lihtsam