Inhaltsformat: einfacher String und Objekt-Array
Auf dieser Seite
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 Eigenschafttextimage_url: ein Verweis auf ein Bild mit der Eigenschaftimage_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