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)
OpenAI Responses `/v1/responses`	`text.format.type: "json_schema"`	Abhaengig von den Faehigkeiten des Upstream-Modells

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": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    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": "John Smith", "age": 28, "city": "San Francisco"}

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<AIHUBMIX_API_KEY>",
  baseURL: "https://aihubmix.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [
    { role: "user", content: "Extract the following information: John Smith, 28 years old, San Francisco" },
  ],
  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,
      },
    },
  },
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data);

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AIHUBMIX_API_KEY>" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    "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
        }
      }
    }
  }'

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": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    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": "John Smith", "age": 28, "city": "San Francisco"}

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": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    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)

curl https://aihubmix.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <AIHUBMIX_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Extract the following information: John Smith, 28 years old, San Francisco"}
    ],
    "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
        }
      }
    }
  }'

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
Transparenter Fallback: Selbst wenn die Modellversion, die Ihre Anfrage letztlich verarbeitet, keine strukturierten Ausgaben unterstützt, wird die Anfrage normal abgeschlossen; die Herabstufung wird im Antwort-Header angezeigt
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": "Extract info: John Smith, 28 years old"}],
        "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
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": "John Smith", "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

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.

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

​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

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