> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Strukturierte Ausgaben (Structured Outputs)

> Modellausgaben per JSON Schema einschraenken (Structured Outputs) -- unterstuetzt response_format und output_config.format fuer OpenAI, Anthropic Claude, Gemini u. a. Modelle, inklusive automatischer Graceful Degradation und protokolluebergreifender Konvertierung.

## 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

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

| 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](#automatische-graceful-degradation)). Die Anfrage schlaegt dadurch nicht fehl.

***

## Schnellstart

### OpenAI-Protokoll (empfohlen)

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

<CodeGroup>
  ```python Python theme={null}
  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"}
  ```

  ```typescript Node.js theme={null}
  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: "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,
        },
      },
    },
  });

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

  ```bash cURL theme={null}
  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": "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
          }
        }
      }
    }'
  ```
</CodeGroup>

### 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 Python theme={null}
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`.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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": "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
          }
        }
      }
    }'
  ```
</CodeGroup>

***

## Hinweise zum Schema-Aufbau

### Pflichtfelder

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

```json theme={null}
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "score": { "type": "number" }
  },
  "required": ["name", "score"],
  "additionalProperties": false
}
```

### Verschachtelte Objekte

Verschachtelte `object`-Typen benoetigen ebenfalls `additionalProperties: false`:

```json theme={null}
{
  "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)                                            |

<Tip>
  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.
</Tip>

***

## 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 Python theme={null}
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               |

<Warning>
  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.
</Warning>

***

## Haeufig gestellte Fragen

<AccordionGroup>
  <Accordion title="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](https://aihubmix.com/models) einsehen.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    1. Konvertierung von `response_format` nach `output_config.format`
    2. Entfernung von Anthropic-inkompatiblen Schema-Schluesselwoertern (`minimum`, `maxLength` etc.)
    3. 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.
  </Accordion>

  <Accordion title="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:

    ```json theme={null}
    {
      "output_config": {
        "format": {
          "type": "json_schema",
          "schema": { ... }
        }
      },
      "reasoning": {
        "effort": "high"
      }
    }
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>