input_image vs image_url: Die beiden Syntaxen
Auf dieser Seite
Zwei APIs, zwei Syntaxen
xAI bietet zwei Endpunkte zur Interaktion mit Grok an, und jeder verwendet eine unterschiedliche Syntax zum Senden von Bildern. Das Verständnis dieser Unterschiede ist unerlässlich, um korrekten Code zu schreiben und frustrierende Fehler zu vermeiden.
Responses API: input_image (empfohlen)
Die Responses API ist der neue primäre Endpunkt von xAI. Neue Funktionen werden hier zuerst hinzugefügt. Dies ist die API, die für jedes neue Projekt priorisiert werden sollte.
Syntax
{
"model": "grok-4.5",
"store": false,
"input": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Beschreibe dieses Bild."
}
]
}
Eigenschaften
- Der Typ ist
input_image(nichtimage_url) - Die URL oder der Data URI geht direkt in
image_url(kein verschachteltes Objekt) detailbefindet sich auf derselben Ebene wieimage_url- Text verwendet den Typ
input_text - Das
input-Array ersetzt dasmessages-Array aus Chat Completions
Python SDK
response = client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Beschreibe dieses Bild."
}
],
store=False
)
print(response.output_text)
Chat Completions API: image_url (Legacy)
Die Chat Completions API ist der Legacy-Endpunkt, der zur Kompatibilität mit bestehenden OpenAI SDKs aufrechterhalten wird. Wenn Sie Code migrieren, der für OpenAI geschrieben wurde, erleichtert diese API den Übergang.
Syntax
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Beschreibe dieses Bild."
}
]
}
]
}
Eigenschaften
- Der Typ ist
image_url(nichtinput_image) - Die URL befindet sich in einem verschachtelten
image_url.url-Objekt (doppelte Verschachtelung) detailbefindet sich innerhalb desimage_url-Objekts- Text verwendet den Typ
text(nichtinput_text) - Nachrichten haben ein
role(system, user, assistant)
Python mit OpenAI SDK
from openai import OpenAI
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.5",
messages=[{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Beschreibe dieses Bild."
}
]
}]
)
print(response.choices[0].message.content)
Vergleichstabelle
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Status | Primär (empfohlen) | Legacy (Kompatibilität) |
| Bildtyp | input_image | image_url |
| Texttyp | input_text | text |
| Bild-URL | image_url: "..." | image_url.url: "..." |
| Zustandsverwaltung | Zustandsbehaftet (previous_response_id) | Zustandslos (alles erneut senden) |
| Speicherung | store: true/false | Nein (zustandslos) |
| Server-Tools | web_search, x_search, code_interpreter | Begrenzt |
Häufige Syntaxfehler
Fehler 1: Vermischung der Formate
# FALSCH — Syntax von Chat Completions in der Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nein!
]
# RICHTIG — Syntax der Responses API
input=[
{"type": "input_image", "image_url": "..."} # Ja!
]
Fehler 2: Vergessen der verschachtelten Struktur in Chat Completions
# FALSCH — Direkte URL in Chat Completions
{"type": "image_url", "image_url": "https://..."} # Nein!
# RICHTIG — Verschachteltes Objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Ja!
Fehler 3: Verwendung von “text” statt “input_text”
# FALSCH — "text"-Typ in der Responses API
input=[
{"type": "text", "text": "Beschreibe."} # Nein!
]
# RICHTIG
input=[
{"type": "input_text", "text": "Beschreibe."} # Ja!
]
Wann welche API verwenden
- Neues Projekt: Nutzen Sie die Responses API. Sie bietet Zugriff auf die neuesten Funktionen und die Konversationspeicherung.
- Migration von OpenAI: Beginnen Sie mit Chat Completions, um Codeänderungen zu minimieren, und migrieren Sie dann schrittweise zur Responses API.
- Sensible Bilder: Responses API mit
store: falseoder Chat Completions API (von Natur aus zustandslos)
Wichtige Erkenntnisse
- Die Responses API verwendet
input_image+input_text, die Chat Completions API verwendetimage_url+text - Die URL-Struktur unterscheidet sich: direkt in Responses, verschachtelt in Chat Completions
- Die Responses API ist die empfohlene Wahl für alle neuen Entwicklungen
- Mischen Sie niemals Syntaxen aus beiden APIs in derselben Anfrage
- Prüfen Sie immer den Objekttyp (
input_imagevs.image_url), um stille Fehler zu vermeiden
Testen Sie Ihr Wissen
xAI API Vision: Formate, Tokens, Syntaxen – ist alles an Ort und Stelle?
1. Wie senden Sie ein Bild an die API?
Antwort: Über URL oder Base64, in einer Nachricht mit gemischtem Inhalt – unter Beachtung der dokumentierten Format- und Größenbeschränkungen.
2. Was steuert der detail-Parameter (auto, low, high)?
Antwort: Analysegranularität und Kosten: low spart Tokens für grobe Anwendungsfälle, high maximiert die Präzision (OCR, feine Details), auto lässt die API entscheiden.
3. Wie wird die Kosten eines Bildes berechnet?
Antwort: In Bild-Token – von 256 bis 1792 je nach Auflösung und Detailgrad: Die Anpassung Ihrer Bilder und Ihres Detailgrads ist der erste Optimierungslieferant.
4. Was ermöglicht der Vergleich mehrerer Bilder?
Antwort: Das Senden mehrerer Bilder in einer einzigen Anfrage und das Nachdenken darüber – Unterschiede, Entwicklungen, Konsistenz – ohne Begrenzung der Anzahl der Bilder pro Anfrage.
5. input_image oder image_url: Welches wählen?
Antwort: input_image ist die moderne Syntax der Responses API; image_url bleibt als Legacy-Syntax der Chat Completions bestehen – für neuen Code ist die moderne Syntax zwingend erforderlich.
Gutes Format, gutes Detail, gute Syntax: Vision wird wie Text gesteuert – bis hin zum Token.