Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Turinio formatas: paprasta eilutė ir objektų masyvas

Paskaita 3 iš 12 Atnaujinta 2026 m. liepos 30 d. Kūrėjas
Šiame puslapyje
  1. Du turinio lauko formatai
  2. Eilutės formatas: dažniausias atvejis
  3. Masyvo formatas: multimedinis turinys
  4. Kada naudoti kurį formatą?
  5. Techniniai apribojimai paveikslėliams
  6. Svarbiausi punktai

Du turinio lauko formatai

xAI „Chat Completions“ API kiekvieno pranešimo content laukas priima du skirtingus formatus. Pasirinkimas priklauso nuo to, ką siunči modeliui: gryną tekstą ar multimedinį turinį (tekstas + paveikslėliai).

Eilutės formatas: dažniausias atvejis

Grynai tekstiniams pranešimams content laukas yra paprasta eilutė:

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

Tai formatas, kurį naudosite absoliučia dauguma atvejų. Jis paprastas, skaitomas ir pakankamas visiems tekstiniams ryšiams su Grok.

system pranešimui beveik visada naudojamas eilutės formatas:

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

Masyvo formatas: multimedinis turinys

Kai kartu su tekstu reikia siųsti paveikslėlius, content laukas tampa tipizuotų objektų masyvu. Kiekvienas objektas turi type lauką, nurodantį jo pobūdį.

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

Galimi objektų tipai

Turinio masyvas priima dviejų tipų objektus:

  • text: teksto blokas su text savybe
  • image_url: nuoroda į paveikslėlį su image_url savybe

Viename pranešime gali derinti tiek objektų, kiek reikia. Pavyzdžiui, jei nori paprašyti modelio palyginti du paveikslėlius:

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

Paveikslėlių detail parametras

Kiekvienas image_url objektas priima nebūtiną detail parametrą, kuris valdo analizės skiriamąją gebą:

  • auto: modelis automatiškai pasirenka detalumo lygį (numatytoji reikšmė)
  • low: greita ir ekonomiška analizė, pakankama paprastiems paveikslėliams (piktogramoms, pagrindinėms schemoms)
  • high: išsami analizė, rekomenduojama sudėtingiems paveikslėliams (dokumentams, nuotraukoms, sąsajoms)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Detalumo lygio pasirinkimas tiesiogiai veikia sunaudojamų žetonų skaičių, taigi ir užklausos kainą.

Kada naudoti kurį formatą?

Taisyklė paprasta:

  • Tik tekstas → eilutės formatas (paprastesnis, skaitomesnis)
  • Tekstas + paveikslėliai → masyvo formatas (būtinas multimediniam turiniui)
  • Tik paveikslėliai → masyvo formatas tik su image_url objektais

Masyvo formatas su vienu text objektu funkciškai lygiavertis eilutės formatui, bet be reikalo išplėstas:

// Ekvivalentu, bet be reikalo sudėtinga
{"content": [{"type": "text", "text": "Hello"}]}

// Geriau rinktis šią formą
{"content": "Hello"}

Techniniai apribojimai paveikslėliams

Prieš siųsdamas paveikslėlius xAI API, atsižvelk į šiuos limitus:

  • Maksimalus dydis: 20 MiB vienam paveikslėliui
  • Priimami formatai: tik JPG, JPEG, PNG (jokių GIF, WebP ar SVG)
  • Skaičius: joks limitas paveikslėlių skaičiui vienoje užklausoje
  • Suderinami modeliai: tik grok-4.5 ir naujesni

Paveikslėlius galima pateikti naudojant viešą URL arba užkoduojant juos base64 formatu tiesiai URL eilutėje (formatas data:image/jpeg;base64,...).

Svarbiausi punktai

  • content laukas priima paprastą eilutę (tekstui) arba objektų masyvą (multimediniam turiniui)
  • Masyvo formatas naudoja objektus su type lauku: "text" arba "image_url"
  • detail parametras (auto, low, high) valdo paveikslėlių analizės skiriamąją gebą
  • Paveikslėlių dydis ribojamas iki 20 MiB (JPG/PNG formatu), ir jiems reikia grok-4.5 arba naujesnio modelio
  • Siųsdamas tik tekstą, naudok eilutės formatą – jis skaitomesnis ir paprastesnis