Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Il-format tal-kontenut: string sempliċi u array ta' oġġetti

Lezzjoni 3 / 12 Aġġornat 30 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Żewġ formati għall-qasam content
  2. Il-format string: il-każ l-aktar komuni
  3. Il-format array: kontenut multimodali
  4. Meta tuża liema format?
  5. Restizzjonijiet tekniċi għall-immaġnijiet
  6. Punti Ewlenin

Żewġ formati għall-qasam content

Il-qasam content ta’ kull messaġġ jaċċetta żewġ formati differenti fl-API ta’ Chat Completions ta’ xAI. L-għażla tiddependi fuq x’tibgħat lill-mudell: test sempliċi jew kontenut multimodali (test + immaġnijiet).

Il-format string: il-każ l-aktar komuni

Għal messaġġi ta’ test pur, il-qasam content huwa string sempliċi:

{
  "role": "user",
  "content": "Spjega kif jaħdem it-transformer."
}

Dan huwa l-format li tuża fil-maġġoranza l-kbira tal-każijiet. Huwa sempliċi, leġibbli, u biżżejjed għall-interazzjonijiet kollha tat-test ma’ Grok.

Għall-messaġġ system, il-format string jintuża kważi dejjem:

{
  "role": "system",
  "content": "Inti espert fl-arkitettura tas-softwer. Wieġeb bl-Ingliż b'eżempji ta' kodiċi Python."
}

Il-format array: kontenut multimodali

Meta jkollok bżonn tibgħat immaġnijiet flimkien mat-test, il-qasam content isir array ta’ oġġetti ttajpjati. Kull oġġett għandu qasam type li jindika n-natura tiegħu.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "X'turi din l-immaġni?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

Tipi ta’ oġġetti disponibbli

L-array tal-kontenut jaċċetta żewġ tipi ta’ oġġetti:

  • text: blokk ta’ test bil-proprjetà text
  • image_url: referenza għal immaġni bil-proprjetà image_url

Tista’ tgħaqqad kemm oġġetti trid f’messaġġ wieħed. Pereżempju, biex titlob lill-mudell iqabbel żewġ immaġnijiet:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Qabbel dawn iż-żewġ dijagrammi tal-arkitettura."},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
  ]
}

Il-parametru detail għall-immaġnijiet

Kull oġġett image_url jaċċetta parametru fakultattiv detail li jikkontrolla r-riżoluzzjoni tal-analiżi:

  • auto: il-mudell jagħżel awtomatikament il-livell tad-dettall (valur predefinit)
  • low: analiżi mgħaġġla u ekonomika, biżżejjed għal immaġnijiet sempliċi (ikoni, dijagrammi bażiċi)
  • high: analiżi dettaljata, rakkomandata għal immaġnijiet kumplessi (dokumenti, ritratti, interfaċċi)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

L-għażla tal-livell tad-dettall taffettwa direttament in-numru ta’ tokens ikkunsmati u għalhekk l-ispiża tat-talba.

Meta tuża liema format?

Ir-regola hija sempliċi:

  • Test biss → format string (aktar sempliċi, aktar leġibbli)
  • Test + immaġnijiet → format array (meħtieġ għall-multimodali)
  • Immaġnijiet biss → format array b’oġġetti image_url biss

Format array b’oġġett text wieħed biss huwa funzjonalment ekwivalenti għall-format string, iżda mhux meħtieġ u twil żejjed:

// Ekwivalenti iżda mhux meħtieġament kumpless
{"content": [{"type": "text", "text": "Hello"}]}

// Ippreferi din il-forma
{"content": "Hello"}

Restizzjonijiet tekniċi għall-immaġnijiet

Qabel ma tibgħat immaġnijiet lill-API ta’ xAI, żomm f’moħħok dawn il-limiti:

  • Daqs massimu: 20 MiB għal kull immaġni
  • Formati aċċettati: JPG, JPEG, PNG biss (l-ebda GIF, WebP, jew SVG)
  • Għadd: l-ebda limitu fuq in-numru ta’ immaġnijiet għal kull talba
  • Mudelli kompatibbli: grok-4.5 u ogħla biss

L-immaġnijiet jistgħu jiġu pprovduti permezz ta’ URL pubbliku jew inkodifikati f’base64 ġewwa l-URL innifsu (format data:image/jpeg;base64,...).

Punti Ewlenin

  • Il-qasam content jaċċetta string sempliċi (test) jew array ta’ oġġetti (multimodali)
  • Il-format array juża oġġetti b’qasam type: "text" jew "image_url"
  • Il-parametru detail (auto, low, high) jikkontrolla r-riżoluzzjoni tal-analiżi għall-immaġnijiet
  • L-immaġnijiet huma limitati għal 20 MiB f’JPG/PNG u jeħtieġu grok-4.5 jew ogħla
  • Uża l-format string meta tibgħat test biss—huwa aktar leġibbli u sempliċi