Salt la conținutul principal
Română— Alege o limbă
Meniu

Formatul conținutului: șir simplu și tablou de obiecte

Lecția 3 din 12 Actualizată 30 iulie 2026 Dezvoltator
Pe această pagină
  1. Două formate pentru câmpul content
  2. Formatul șir: cazul cel mai frecvent
  3. Formatul tablou: conținut multimodal
  4. Când să utilizați fiecare format?
  5. Constrângeri tehnice pentru imagini
  6. Puncte cheie

Două formate pentru câmpul content

Câmpul content al fiecărui mesaj acceptă două formate diferite în API-ul xAI Chat Completions. Alegerea depinde de ceea ce trimiteți modelului: text simplu sau conținut multimodal (text + imagini).

Formatul șir: cazul cel mai frecvent

Pentru mesajele care conțin exclusiv text, câmpul content este un șir simplu:

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

Acesta este formatul pe care îl veți utiliza în marea majoritate a cazurilor. Este simplu, lizibil și suficient pentru toate interacțiunile textuale cu Grok.

Pentru mesajul system, se utilizează aproape întotdeauna formatul șir:

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

Formatul tablou: conținut multimodal

Atunci când trebuie să trimiteți imagini împreună cu text, câmpul content devine un tablou de obiecte tipizate. Fiecare obiect posedă un câmp type care îi indică natura.

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

Tipurile de obiecte disponibile

Tabloul de conținut acceptă două tipuri de obiecte:

  • text: un bloc de text cu proprietatea text
  • image_url: o referință către o imagine cu proprietatea image_url

Puteți combina câte obiecte doriți într-un singur mesaj. De exemplu, pentru a cere modelului să compare două imagini:

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

Parametrul detail pentru imagini

Fiecare obiect image_url acceptă un parametru opțional detail care controlează rezoluția analizei:

  • auto: modelul alege automat nivelul de detaliu (valoarea implicită)
  • low: analiză rapidă și economică, suficientă pentru imagini simple (pictograme, diagrame de bază)
  • high: analiză detaliată, recomandată pentru imagini complexe (documente, fotografii, interfețe)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Alegerea nivelului de detaliu impactează direct numărul de tokeni consumați și, prin urmare, costul cererii.

Când să utilizați fiecare format?

Regula este simplă:

  • Doar text → format șir (mai simplu, mai lizibil)
  • Text + imagini → format tablou (obligatoriu pentru multimodal)
  • Doar imagini → format tablou cu obiecte exclusiv de tip image_url

Un format tablou care conține un singur obiect text este funcțional echivalent cu formatul șir, dar inutil de verbose:

// Echivalent, dar inutil de complex
{"content": [{"type": "text", "text": "Hello"}]}

// Preferați această formă
{"content": "Hello"}

Constrângeri tehnice pentru imagini

Înainte de a trimite imagini către API-ul xAI, rețineți următoarele limite:

  • Dimensiune maximă: 20 MiB per imagine
  • Formate acceptate: doar JPG, JPEG, PNG (fără GIF, WebP sau SVG)
  • Număr: nicio limită privind numărul de imagini per cerere
  • Modele compatibile: doar grok-4.5 și versiunile superioare

Imaginile pot fi furnizate printr-un URL public sau codificate în base64 direct în URL (format data:image/jpeg;base64,...).

Puncte cheie

  • Câmpul content acceptă un șir simplu (text) sau un tablou de obiecte (multimodal)
  • Formatul tablou utilizează obiecte cu un câmp type: "text" sau "image_url"
  • Parametrul detail (auto, low, high) controlează rezoluția analizei pentru imagini
  • Imaginile sunt limitate la 20 MiB în format JPG/PNG și necesită grok-4.5 sau o versiune superioară
  • Utilizați formatul șir atunci când trimiteți doar text – este mai lizibil și mai simplu