Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Inhaltsformat: einfacher String und Objekt-Array

Lektion 3 von 12 Aktualisiert am 30. Juli 2026 Entwickler
Auf dieser Seite
  1. Zwei Formate für das content-Feld
  2. String-Format: der häufigste Fall
  3. Array-Format: multimodaler Inhalt
  4. Wann welches Format verwenden?
  5. Technische Einschränkungen für Bilder
  6. Kernaussagen

Zwei Formate für das content-Feld

Das content-Feld jeder Nachricht im xAI Chat Completions API akzeptiert zwei verschiedene Formate. Die Wahl hängt davon ab, was Sie dem Modell senden: reinen Text oder multimodalen Inhalt (Text + Bilder).

String-Format: der häufigste Fall

Bei rein textbasierten Nachrichten ist das content-Feld ein einfacher String:

{
  "role": "user",
  "content": "Erklären Sie, wie ein Transformer funktioniert."
}

Dies ist das Format, das Sie in den meisten Fällen verwenden werden. Es ist einfach, lesbar und für alle Textinteraktionen mit Grok ausreichend.

Für die system-Nachricht wird das String-Format fast immer verwendet:

{
  "role": "system",
  "content": "Sie sind ein Experte für Softwarearchitektur. Antworten Sie auf Englisch mit Python-Codebeispielen."
}

Array-Format: multimodaler Inhalt

Wenn Sie Bilder zusammen mit Text senden müssen, wird das content-Feld zu einem Array von typisierten Objekten. Jedes Objekt verfügt über ein type-Feld, das seine Art angibt.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Was zeigt dieses Bild?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

Verfügbare Objekttypen

Das Content-Array akzeptiert zwei Objekttypen:

  • text: ein Textblock mit der Eigenschaft text
  • image_url: ein Verweis auf ein Bild mit der Eigenschaft image_url

Sie können in einer einzelnen Nachricht so viele Objekte kombinieren, wie benötigt werden. Zum Beispiel, um das Modell zu bitten, zwei Bilder zu vergleichen:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Vergleichen Sie diese beiden Architekturdiagramme."},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
  ]
}

Der detail-Parameter für Bilder

Jedes image_url-Objekt akzeptiert einen optionalen detail-Parameter, der die Analyseauflösung steuert:

  • auto: das Modell wählt die Detailstufe automatisch (Standardwert)
  • low: schnelle und wirtschaftliche Analyse, ausreichend für einfache Bilder (Symbole, grundlegende Diagramme)
  • high: detaillierte Analyse, empfohlen für komplexe Bilder (Dokumente, Fotografien, Benutzeroberflächen)
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

Die Wahl der Detailstufe wirkt sich direkt auf die Anzahl der verbrauchten Tokens und damit auf die Kosten der Anfrage aus.

Wann welches Format verwenden?

Die Regel ist einfach:

  • Nur Text → String-Format (einfacher, lesbarer)
  • Text + Bilder → Array-Format (erforderlich für multimodale Inhalte)
  • Nur Bilder → Array-Format mit ausschließlich image_url-Objekten

Ein Array-Format mit einem einzigen text-Objekt ist funktional äquivalent zum String-Format, aber unnötig umständlich:

// Äquivalent, aber unnötig komplex
{"content": [{"type": "text", "text": "Hallo"}]}

// Bevorzugen Sie diese Form
{"content": "Hallo"}

Technische Einschränkungen für Bilder

Bevor Sie Bilder an das xAI API senden, sollten Sie folgende Limits beachten:

  • Maximale Größe: 20 MiB pro Bild
  • Akzeptierte Formate: Nur JPG, JPEG und PNG (keine GIF, WebP oder SVG)
  • Anzahl: keine Begrenzung der Anzahl der Bilder pro Anfrage
  • Kompatible Modelle: nur grok-4.5 und höher

Bilder können über eine öffentliche URL bereitgestellt oder in Base64 innerhalb der URL selbst codiert werden (Format data:image/jpeg;base64,...).

Kernaussagen

  • Das content-Feld akzeptiert einen einfachen String (Text) oder ein Objekt-Array (multimodal)
  • Das Array-Format verwendet Objekte mit einem type-Feld: "text" oder "image_url"
  • Der detail-Parameter (auto, low, high) steuert die Analyseauflösung für Bilder
  • Bilder sind auf 20 MiB in JPG/PNG begrenzt und erfordern grok-4.5 oder höher
  • Verwenden Sie das String-Format, wenn Sie nur Text senden – es ist lesbarer und einfacher