Sisällön muoto: yksinkertainen merkkijono ja objektimatriisi
Tällä sivulla
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 ontext-ominaisuusimage_url: viittaus kuvaan, jossa onimage_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