Structured Outputs

Constrain model output format with JSON Schema (Structured Outputs). Supports response_format for OpenAI, output_config.format for Anthropic Claude, and Gemini models, with auto-degradation and cross-protocol translation.

Overview

Structured Outputs force the model’s response to strictly follow a JSON Schema you define, ensuring the return value can be parsed directly by your program without regex or post-processing.

Unlike asking the model to “please return JSON” in the prompt, Structured Outputs rely on Constrained Decoding: the upstream provider compiles the JSON Schema into grammar rules and constrains generation token-by-token during inference, making it impossible for the model to produce output that violates the schema.

Typical use cases:

• Extracting entities and fields from unstructured text
• Classification / labeling / sentiment analysis
• Standardized passing of intermediate results in multi-step reasoning
• Strongly-typed constraints on Agent tool call parameters

Protocol Parameter Comparison

The parameter names differ across the three protocols, but the underlying mechanism is the same: the model output strictly matches the JSON Schema you provide.

Protocol	Parameter	Supported Models
OpenAI Chat /v1/chat/completions	response_format.type: "json_schema"	Claude 4.5+, GPT-4o / GPT-5 series, Gemini series
Anthropic Messages /v1/messages	output_config.format.type: "json_schema"	Claude 4.5+ (direct / Vertex / Bedrock)
OpenAI Responses /v1/responses	text.format.type: "json_schema"	Depends on upstream model capabilities

---

Quick Start

OpenAI Protocol (Recommended)

Works with all models that support Structured Outputs, across providers.

Python

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
        }
      }
    }
  }'

Using Other Models (GLM-5.2 Example)

The same OpenAI protocol parameters work with all models that support Structured Outputs — just switch the model.

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"}

Claude Native Protocol

Call directly with the Anthropic SDK using the output_config.format parameter.

Python

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
        }
      }
    }
  }'

---

Schema Writing Guidelines

Required Fields

All object types must explicitly declare additionalProperties: false; otherwise some upstream providers will reject the request.

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

Nested Objects

Nested object types also require additionalProperties: false:

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

Cross-Protocol Schema Differences

Feature	OpenAI Protocol	Anthropic Protocol
name field	Required	Not supported (automatically handled by the gateway during cross-protocol calls)
strict field	Optional, recommended true	Not supported
Numeric constraints (minimum, maximum, etc.)	Supported	Not supported (automatically stripped by the gateway; does not affect the request)
String constraints (minLength, maxLength)	Supported	Not supported (automatically stripped by the gateway)

When calling Claude models via the OpenAI protocol, the gateway automatically converts the Schema format and strips incompatible keywords — no manual adaptation needed.

---

Auto-Degradation Mechanism

The gateway enables auto-degradation protection for Structured Outputs on all requests by default. When the model or platform does not support it, the gateway will not return an error. Instead, it automatically strips the Schema constraint and marks the degradation reason in a response header. Your request will still receive a normal model response — the output simply won’t be strictly constrained by the Schema.

This means you can safely enable Structured Outputs uniformly on the client side without having to check compatibility for each model:

• Seamless multi-model switching: When switching models between Claude, GPT, Gemini, and GLM with the same codebase, requests won’t fail even if the target model doesn’t support Structured Outputs
• Transparent fallback: Even when the model version that ends up handling your request doesn’t support Structured Outputs, the request still completes normally, with degradation flagged in the response header
• Simplified client logic: No need to maintain a list of “which models support Structured Outputs” — the gateway handles it automatically; the client only needs to check the response header to decide whether additional parsing is needed

Response Header

X-Structured-Output-Degraded: <reason>

reason	Meaning
model_unsupported	The model (or the model on its current platform) does not support Structured Outputs
json_object_unsupported_on_anthropic	json_object mode cannot be converted to the Anthropic format
json_schema_missing_schema	json_schema type was specified but the schema field is missing
schema_keywords_stripped	Some constraint keywords in the Schema were stripped (e.g., minimum, maxLength)

Detection Example

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,
                }
            }
        }
    }
)

# Check if degradation occurred
degraded = response.headers.get("X-Structured-Output-Degraded")
if degraded:
    print(f"Structured Output degraded: {degraded}")
    # The model response is still normal, but the output is not strictly constrained by the Schema
else:
    import json
    data = json.loads(response.json()["choices"][0]["message"]["content"])
    print(data)  # {"name": "John Smith", "age": 28}

---

Difference from json_object Mode

	json_schema (Structured Outputs)	json_object
Output guarantee	Strictly matches the specified Schema	Only guarantees valid JSON
Field control	Field names, types, and required status are all constrained	No constraints
Supported protocols	OpenAI / Anthropic / Responses	OpenAI-compatible protocols only
Claude support	Via output_config.format	Not supported

json_object mode cannot be converted to the Claude native protocol. If you send response_format: {"type": "json_object"} to Claude via the OpenAI protocol, the response header will mark json_object_unsupported_on_anthropic degradation. Use the json_schema type instead.

---

FAQ

Which models support Structured Outputs?

Claude series (via Anthropic API’s output_config.format):

• Opus / Sonnet / Haiku 4.5 and above
• Fable / Mythos 5 and above

OpenAI series (via response_format):

• GPT-4o and above, GPT-5 series

Gemini series (via responseSchema):

• Gemini 2.5 and above

Check each model’s capability tags on the Models page.

Is the JSON Schema modified during cross-protocol calls?

Yes. When calling Claude models via the OpenAI protocol, the gateway automatically:

1. Converts response_format to output_config.format
2. Removes Schema keywords not supported by Anthropic (minimum, maxLength, etc.)
3. Marks schema_keywords_stripped in the response header if any keywords were stripped

The reverse direction (calling OpenAI models via the Claude protocol) is also automatically converted.

Can Structured Outputs be used together with Extended Thinking?

Yes. The format (Structured Outputs) in output_config and the effort (thinking intensity) in reasoning are independent parameters that can be set simultaneously:

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

How does the degradation mechanism compare to other aggregation platforms like OpenRouter?

Most API aggregation platforms return an error outright when a model does not support Structured Outputs. AIHubMix uses a graceful degradation strategy: it automatically strips incompatible parameters, returns the model response normally, and informs the client of the degradation reason via the X-Structured-Output-Degraded response header. Your application will not break because of this.