Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

input_image vs image_url: Die beiden Syntaxen

Lektion 12 von 12 Aktualisiert am 30. Juli 2026 Anfänger
Auf dieser Seite
  1. Zwei APIs, zwei Syntaxen
  2. Responses API: input_image (empfohlen)
  3. Chat Completions API: image_url (Legacy)
  4. Vergleichstabelle
  5. Häufige Syntaxfehler
  6. Wann welche API verwenden
  7. Wichtige Erkenntnisse
  8. Testen Sie Ihr Wissen

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 (nicht image_url)
  • Die URL oder der Data URI geht direkt in image_url (kein verschachteltes Objekt)
  • detail befindet sich auf derselben Ebene wie image_url
  • Text verwendet den Typ input_text
  • Das input-Array ersetzt das messages-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 (nicht input_image)
  • Die URL befindet sich in einem verschachtelten image_url.url-Objekt (doppelte Verschachtelung)
  • detail befindet sich innerhalb des image_url-Objekts
  • Text verwendet den Typ text (nicht input_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: false oder Chat Completions API (von Natur aus zustandslos)

Wichtige Erkenntnisse

  • Die Responses API verwendet input_image + input_text, die Chat Completions API verwendet image_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_image vs. 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.