AiHubMix Documentation Hub

Funktionsueberblick

Strukturierte Ausgaben (Structured Outputs) sorgen dafuer, dass die Antwort des Modells strikt Ihrem definierten JSON Schema folgt. Dadurch kann die Rueckgabe direkt programmatisch geparst werden — ohne regulaere Ausdruecke oder Nachbearbeitung. Im Gegensatz zur Anweisung im Prompt, das Modell solle “bitte JSON zurueckgeben”, basieren Structured Outputs auf Constrained Decoding (eingeschraenkte Dekodierung): Der Upstream-Anbieter kompiliert das JSON Schema in Grammatikregeln und schraenkt die Generierung waehrend der Inferenz Token fuer Token ein. Das Modell kann keine Ausgabe erzeugen, die gegen das Schema verstoesst. Typische Anwendungsfaelle:

Extraktion von Entitaeten und Feldern aus unstrukturiertem Text
Klassifikation / Tagging / Sentimentanalyse
Standardisierte Weitergabe von Zwischenergebnissen bei mehrstufiger Schlussfolgerung
Strenge Typbindung fuer Agent-Tool-Call-Parameter

Parametervergleich nach Protokoll

Die drei Protokolle verwenden unterschiedliche Parameternamen, der zugrunde liegende Mechanismus ist jedoch identisch: Die Modellausgabe entspricht strikt Ihrem JSON Schema.

Protokoll	Parameter	Unterstuetzte Modelle
OpenAI Chat `/v1/chat/completions`	`response_format.type: "json_schema"`	Claude 4.5+, GPT-4o / GPT-5 Serie, Gemini Serie
Anthropic Messages `/v1/messages`	`output_config.format.type: "json_schema"`	Claude 4.5+ (Direktverbindung / Vertex); Bedrock nur 4.5—4.6
OpenAI Responses `/v1/responses`	`text.format.type: "json_schema"`	Abhaengig von den Faehigkeiten des Upstream-Modells

AWS Bedrock Einschraenkungen

Auf AWS Bedrock verwenden Claude 4.7 und hoehere Versionen den Mantle-Inferenzpfad, der derzeit output_config.format nicht unterstuetzt. Das Gateway entfernt automatisch das format-Feld fuer diese Modelle und markiert die Degradierung im Response-Header (siehe unten Graceful Degradation). Die Anfrage schlaegt dadurch nicht fehl.

Schnellstart

OpenAI-Protokoll (empfohlen)

Geeignet fuer alle Modelle, die Structured Outputs unterstuetzen — anbieteruebergreifend einsetzbar.

from openai import OpenAI

client = OpenAI(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "user", "content": "Extrahieren Sie folgende Informationen: Max Mueller, 28 Jahre, Berlin Mitte"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.choices[0].message.content)
print(data)
# {"name": "Max Mueller", "age": 28, "city": "Berlin Mitte"}

Andere Modelle verwenden (Beispiel GLM-5.2)

Dieselben OpenAI-Protokoll-Parameter gelten fuer alle Modelle mit Structured-Output-Unterstuetzung — Sie muessen lediglich das model wechseln.

Python

from openai import OpenAI

client = OpenAI(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com/v1",
)

response = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {"role": "user", "content": "Extrahieren Sie folgende Informationen: Max Mueller, 28 Jahre, Berlin Mitte"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.choices[0].message.content)
print(data)
# {"name": "Max Mueller", "age": 28, "city": "Berlin Mitte"}

Natives Claude-Protokoll

Direkter Aufruf ueber das Anthropic SDK mit dem Parameter output_config.format.

import anthropic

client = anthropic.Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com",
)

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Extrahieren Sie folgende Informationen: Max Mueller, 28 Jahre, Berlin Mitte"}
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.content[0].text)
print(data)

Hinweise zum Schema-Aufbau

Pflichtfelder

Alle Typen vom Typ object muessen explizit additionalProperties: false deklarieren — andernfalls lehnen einige Upstream-Anbieter die Anfrage ab.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "score": { "type": "number" }
  },
  "required": ["name", "score"],
  "additionalProperties": false
}

Verschachtelte Objekte

Verschachtelte object-Typen benoetigen ebenfalls additionalProperties: false:

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      },
      "required": ["name", "email"],
      "additionalProperties": false
    }
  },
  "required": ["user"],
  "additionalProperties": false
}

Schema-Unterschiede zwischen Protokollen

Eigenschaft	OpenAI-Protokoll	Anthropic-Protokoll
`name`-Feld	Erforderlich	Nicht unterstuetzt (wird bei protokolluebergreifenden Aufrufen vom Gateway automatisch behandelt)
`strict`-Feld	Optional, `true` empfohlen	Nicht unterstuetzt
Numerische Constraints (`minimum`, `maximum` etc.)	Unterstuetzt	Nicht unterstuetzt (vom Gateway automatisch bereinigt, ohne Auswirkung auf die Anfrage)
String-Constraints (`minLength`, `maxLength`)	Unterstuetzt	Nicht unterstuetzt (vom Gateway automatisch bereinigt)

Wenn Sie Claude-Modelle ueber das OpenAI-Protokoll aufrufen, konvertiert das Gateway das Schema-Format automatisch und bereinigt inkompatible Schluesselwoerter — eine manuelle Anpassung ist nicht erforderlich.

Automatische Graceful Degradation

Das Gateway aktiviert standardmaessig den automatischen Degradierungsschutz fuer Structured Outputs bei allen Anfragen. Wenn ein Modell oder eine Plattform Structured Outputs nicht unterstuetzt, gibt das Gateway keinen Fehler zurueck, sondern entfernt automatisch die Schema-Einschraenkung und markiert den Degradierungsgrund im Response-Header. Ihre Anfrage erhaelt weiterhin eine normale Modellantwort — nur ohne erzwungene Schema-Bindung. Das bedeutet, dass Sie Structured Outputs bedenkenlos clientseitig einheitlich aktivieren koennen, ohne fuer jedes Modell Kompatibilitaetspruefungen durchfuehren zu muessen:

Sorgloses Wechseln zwischen Modellen: Derselbe Code funktioniert beim Wechsel zwischen Claude, GPT, Gemini und GLM — selbst wenn das Zielmodell Structured Outputs nicht unterstuetzt, schlaegt die Anfrage nicht fehl
Transparentes Fallback-Routing: Wenn der primaere Kanal nicht verfuegbar ist und das Fallback-Routing auf einen Ersatzkanal umleitet, wird die Anfrage auch dann erfolgreich abgeschlossen, wenn die Modellversion des Ersatzkanals Structured Outputs nicht unterstuetzt
Vereinfachte Client-Logik: Sie muessen keine Liste pflegen, welche Modelle Structured Outputs unterstuetzen — das Gateway uebernimmt dies automatisch; der Client muss lediglich den Response-Header pruefen, um zu entscheiden, ob zusaetzliches Parsing erforderlich ist

Response-Header

X-Structured-Output-Degraded: <reason>

reason	Bedeutung
`model_unsupported`	Das Modell (bzw. das Modell auf der aktuellen Plattform) unterstuetzt keine Structured Outputs
`json_object_unsupported_on_anthropic`	Der `json_object`-Modus kann nicht in das Anthropic-Format konvertiert werden
`json_schema_missing_schema`	Der Typ `json_schema` wurde angegeben, aber das `schema`-Feld fehlt
`schema_keywords_stripped`	Bestimmte Constraint-Schluesselwoerter im Schema wurden bereinigt (z. B. `minimum`, `maxLength`)

Erkennungsbeispiel

Python

import httpx

response = httpx.post(
    "https://aihubmix.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer <AIHUBMIX_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "claude-sonnet-5",
        "messages": [{"role": "user", "content": "Informationen extrahieren: Max Mueller, 28 Jahre"}],
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "person",
                "strict": True,
                "schema": {
                    "type": "object",
                    "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                    "required": ["name", "age"],
                    "additionalProperties": False,
                }
            }
        }
    }
)

# Pruefen, ob eine Degradierung stattgefunden hat (z. B. wenn die Anfrage an einen Bedrock-Kanal ohne Unterstuetzung geroutet wurde)
degraded = response.headers.get("X-Structured-Output-Degraded")
if degraded:
    print(f"Strukturierte Ausgabe degradiert: {degraded}")
    # Die Modellantwort ist weiterhin normal, jedoch nicht durch das Schema erzwungen
else:
    import json
    data = json.loads(response.json()["choices"][0]["message"]["content"])
    print(data)  # {"name": "Max Mueller", "age": 28}

Unterschied zum `json_object`-Modus

	`json_schema` (Structured Outputs)	`json_object`
Ausgabegarantie	Strikte Uebereinstimmung mit dem angegebenen Schema	Nur garantiert gueltiges JSON
Feldkontrolle	Feldnamen, Typen und Pflichtangaben sind eingeschraenkt	Keine Einschraenkungen
Unterstuetzte Protokolle	OpenAI / Anthropic / Responses	Nur OpenAI-kompatible Protokolle
Claude-Unterstuetzung	Ueber `output_config.format`	Nicht unterstuetzt

Der json_object-Modus unterstuetzt keine Konvertierung in das native Claude-Protokoll. Wenn Sie ueber das OpenAI-Protokoll response_format: {"type": "json_object"} an Claude senden, wird im Response-Header die Degradierung json_object_unsupported_on_anthropic markiert. Es wird empfohlen, direkt den Typ json_schema zu verwenden.

Haeufig gestellte Fragen

Welche Modelle unterstuetzen Structured Outputs?

Claude-Serie (ueber output_config.format der Anthropic API):

Opus / Sonnet / Haiku 4.5 und hoeher
Fable / Mythos 5 und hoeher
Bedrock-Plattform nur 4.5—4.6; Vertex AI wie Direktverbindung

OpenAI-Serie (ueber response_format):

GPT-4o und hoeher, GPT-5 Serie

Gemini-Serie (ueber responseSchema):

Gemini 2.5 und hoeher

Die Faehigkeitstags der einzelnen Modelle koennen Sie auf der Modelllistenseite einsehen.

Warum unterstuetzen einige Claude-Modelle auf Bedrock keine Structured Outputs?

Claude 4.7+ auf AWS Bedrock verwendet den neuen Mantle-Inferenzpfad, der den Parameter output_config.format derzeit nicht akzeptiert. Das Gateway behandelt dies automatisch: Es entfernt das format-Feld und liefert die Antwort normal zurueck, wobei gleichzeitig der Degradierungs-Header X-Structured-Output-Degraded: model_unsupported gesetzt wird. Claude 4.5—4.6 wird auf Bedrock vollstaendig unterstuetzt.

Wird das JSON Schema bei protokolluebergreifenden Aufrufen modifiziert?

Ja. Wenn Claude-Modelle ueber das OpenAI-Protokoll aufgerufen werden, fuehrt das Gateway automatisch folgende Schritte durch:

Konvertierung von response_format nach output_config.format
Entfernung von Anthropic-inkompatiblen Schema-Schluesselwoertern (minimum, maxLength etc.)
Falls Schluesselwoerter bereinigt wurden, Markierung im Response-Header mit schema_keywords_stripped

Die umgekehrte Richtung (Claude-Protokoll zum Aufruf von OpenAI-Modellen) wird ebenso automatisch konvertiert.

Koennen Structured Outputs und Extended Thinking gleichzeitig verwendet werden?

Ja. format (Structured Outputs) in output_config und effort (Denkintensitaet) in reasoning sind unabhaengige Parameter und koennen gleichzeitig gesetzt werden:

{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": { ... }
    }
  },
  "reasoning": {
    "effort": "high"
  }
}

Wie unterscheidet sich der Degradierungsmechanismus im Vergleich zu anderen Aggregationsplattformen wie OpenRouter?

Die meisten API-Aggregationsplattformen geben einen Fehler zurueck, wenn ein Modell Structured Outputs nicht unterstuetzt. AIHubMix verfolgt eine Strategie der Graceful Degradation: Inkompatible Parameter werden automatisch entfernt, die Modellantwort wird normal zurueckgegeben, und ueber den Response-Header X-Structured-Output-Degraded wird der Client ueber den Degradierungsgrund informiert. Ihre Anwendung wird dadurch nicht unterbrochen.

​Funktionsueberblick

​Parametervergleich nach Protokoll

​AWS Bedrock Einschraenkungen

​Schnellstart

​OpenAI-Protokoll (empfohlen)

​Andere Modelle verwenden (Beispiel GLM-5.2)

​Natives Claude-Protokoll

​Hinweise zum Schema-Aufbau

​Pflichtfelder

​Verschachtelte Objekte

​Schema-Unterschiede zwischen Protokollen

​Automatische Graceful Degradation

​Response-Header

​Erkennungsbeispiel

​Unterschied zum json_object-Modus

​Haeufig gestellte Fragen

Funktionsueberblick

Parametervergleich nach Protokoll

AWS Bedrock Einschraenkungen

Schnellstart

OpenAI-Protokoll (empfohlen)

Andere Modelle verwenden (Beispiel GLM-5.2)

Natives Claude-Protokoll

Hinweise zum Schema-Aufbau

Pflichtfelder

Verschachtelte Objekte

Schema-Unterschiede zwischen Protokollen

Automatische Graceful Degradation

Response-Header

Erkennungsbeispiel

Unterschied zum `json_object`-Modus

Haeufig gestellte Fragen