Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Sisällön muoto: yksinkertainen merkkijono ja objektimatriisi

Oppitunti 3 / 12 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi muotoa content-kentälle
  2. Merkkijonomuoto: yleisin tapaus
  3. Matriisimuoto: multimodaalinen sisältö
  4. Milloin käyttää kumpaakin muotoa?
  5. Kuvia koskevat tekniset rajoitukset
  6. Keskeiset asiat

Kaksi muotoa content-kentälle

xAI Chat Completions -rajapinnassa jokaisen viestin content-kenttä hyväksyy kahta eri muotoa. Valinta riippuu siitä, lähetätkö mallille pelkkää tekstiä vai multimodaalista sisältöä (teksti + kuvat).

Merkkijonomuoto: yleisin tapaus

Puhtaasti tekstipohjaisissa viesteissä content-kenttä on yksinkertainen merkkijono:

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

Tämä on muoto, jota käytät valtaosassa tapauksista. Se on yksinkertainen, luettava ja riittää kaikkiin Grokin kanssa käytäviin tekstivuorovaikutuksiin.

system-viestissä käytetään lähes aina merkkijonomuotoa:

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

Matriisimuoto: multimodaalinen sisältö

Kun sinun tarvitsee lähettää kuvia tekstin lisäksi, content-kentästä tulee tyypitettyjen objektien matriisi. Jokaisella objektilla on type-kenttä, joka ilmoittaa sen luonteen.

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

Käytettävissä olevat objektityypit

Sisältömatriisi hyväksyy kahta objektityyppiä:

  • text: tekstilohko, jossa on text-ominaisuus
  • image_url: viittaus kuvaan, jossa on image_url-ominaisuus

Voit yhdistää samaan viestiin niin monta objektia kuin tarvitset. Esimerkiksi, jos haluat pyytää mallia vertailemaan kahta kuvaa:

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

Kuvien detail-parametri

Jokainen image_url-objekti hyväksyy valinnaisen detail-parametrin, joka ohjaa analyysin tarkkuutta:

  • auto: malli valitsee automaattisesti tarkkuustason (oletusarvo)
  • low: nopea ja taloudellinen analyysi, riittää yksinkertaisille kuville (kuvakkeet, peruskaaviot)
  • high: yksityiskohtainen analyysi, suositeltu monimutkaisille kuville (asiakirjat, valokuvat, käyttöliittymät)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Tarkkuustason valinta vaikuttaa suoraan kulutettujen tokenien määrään ja siten pyynnön kustannuksiin.

Milloin käyttää kumpaakin muotoa?

Sääntö on yksinkertainen:

  • Vain tekstiä → merkkijonomuoto (yksinkertaisempi, luettavampi)
  • Tekstiä + kuvia → matriisimuoto (vaaditaan multimodaalisuuteen)
  • Vain kuvia → matriisimuoto, jossa on vain image_url-objekteja

Matriisimuoto, jossa on vain yksi text-objekti, on toiminnallisesti vastaava kuin merkkijonomuoto, mutta tarpeettoman puhelias:

// Vastaava mutta tarpeettoman monimutkainen
{"content": [{"type": "text", "text": "Hello"}]}

// Suosi tätä muotoa
{"content": "Hello"}

Kuvia koskevat tekniset rajoitukset

Ennen kuvien lähettämistä xAI-rajapintaan, pidä nämä rajat mielessäsi:

  • Enimmäiskoko: 20 MiB kuvaa kohden
  • Hyväksytyt muodot: Vain JPG, JPEG, PNG (ei GIF, WebP tai SVG)
  • Määrä: ei rajoitusta kuvien määrälle pyyntöä kohden
  • Yhteensopivat mallit: vain grok-4.5 ja uudemmat

Kuvat voidaan toimittaa julkisen URL-osoitteen kautta tai koodata base64-muodossa suoraan URL-osoitteeseen (muoto data:image/jpeg;base64,...).

Keskeiset asiat

  • content-kenttä hyväksyy yksinkertaisen merkkijonon (teksti) tai objektimatriisin (multimodaalinen)
  • Matriisimuoto käyttää objekteja, joissa on type-kenttä: "text" tai "image_url"
  • detail-parametri (auto, low, high) ohjaa kuvien analyysin tarkkuutta
  • Kuvat ovat rajoitettu 20 MiB:n kokoon JPG/PNG-muodoissa ja vaativat grok-4.5:n tai uudemman version
  • Käytä merkkijonomuotoa, kun lähetät vain tekstiä – se on luettavampi ja yksinkertaisempi