構造化出力 Structured Outputs

機能概要

構造化出力（Structured Outputs）を使用すると、モデルの応答が定義した JSON Schema に厳密に従うようになり、正規表現や後処理なしでプログラムから直接パースできる戻り値が保証されます。プロンプトでモデルに「JSONで返してください」と依頼する方法とは異なり、構造化出力は制約付きデコーディング（Constrained Decoding）に基づいています。上流プロバイダが JSON Schema を文法規則にコンパイルし、推論過程でトークンごとに生成を制約するため、モデルが Schema に違反するコンテンツを出力することは不可能です。典型的なユースケース：

非構造化テキストからのエンティティ・フィールド抽出
分類 / ラベリング / 感情分析
マルチステップ推論における中間結果の標準化された受け渡し
Agent ツール呼び出しパラメータの厳密な型制約

各プロトコルのパラメータ対照表

3つのプロトコルでパラメータ名は異なりますが、基本的なメカニズムは同じです：モデルの出力が提供された JSON Schema に厳密に一致します。

プロトコル	パラメータ	対応モデル
OpenAI Chat `/v1/chat/completions`	`response_format.type: "json_schema"`	Claude 4.5+、GPT-4o / GPT-5 シリーズ、Gemini シリーズ
Anthropic Messages `/v1/messages`	`output_config.format.type: "json_schema"`	Claude 4.5+（直接接続 / Vertex / Bedrock）
OpenAI Responses `/v1/responses`	`text.format.type: "json_schema"`	上流モデルの対応状況に準ずる

クイックスタート

OpenAI プロトコル（推奨）

構造化出力に対応するすべてのモデルに適用でき、プロバイダ横断で共通して使用できます。

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

他のモデルの使用（GLM-5.2 の例）

同じ OpenAI プロトコルのパラメータが構造化出力に対応するすべてのモデルに適用でき、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 ネイティブプロトコル

Anthropic SDK を使用して直接呼び出します。パラメータは 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
        }
      }
    }
  }'

Schema の記述ポイント

必須フィールド

すべての object 型には additionalProperties: false を明示的に宣言する必要があります。これがない場合、一部の上流プロバイダがリクエストを拒否します。

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

ネストされたオブジェクト

ネストされた object にも同様に 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 差異

特性	OpenAI プロトコル	Anthropic プロトコル
`name` フィールド	必須	非対応（ゲートウェイがクロスプロトコル呼び出し時に自動処理）
`strict` フィールド	任意、`true` 推奨	非対応
数値制約 (`minimum`, `maximum` 等)	対応	非対応（ゲートウェイが自動クリーニング、リクエストに影響なし）
文字列制約 (`minLength`, `maxLength`)	対応	非対応（ゲートウェイが自動クリーニング）

OpenAI プロトコル経由で Claude モデルを呼び出す場合、ゲートウェイが Schema フォーマットを自動変換し、互換性のないキーワードをクリーニングするため、手動での対応は不要です。

自動デグレードメカニズム

ゲートウェイはデフォルトですべてのリクエストに対して構造化出力の自動デグレード保護を有効にしています。モデルまたはプラットフォームがサポートしていない場合、ゲートウェイはエラーを返さず、自動的に Schema 制約を除去し、レスポンスヘッダーにデグレードの理由を記録します。リクエストは引き続き正常なモデル応答を受け取りますが、出力は Schema による強制制約を受けません。これにより、クライアント側で構造化出力を統一的に有効化でき、モデルごとの互換性判断を行う必要がなくなります：

マルチモデル切り替えが安心：同一のコードで Claude、GPT、Gemini、GLM 間でモデルを切り替える際、対象モデルが構造化出力をサポートしていなくてもリクエストはエラーになりません
フォールバック透過：リクエストを実際に処理するモデルバージョンが構造化出力に対応していない場合でも、リクエストは正常に完了し、レスポンスヘッダーでデグレードが示されます
クライアントロジックの簡素化：「どのモデルが構造化出力をサポートしているか」のリストを管理する必要がなく、ゲートウェイが自動処理済み。クライアントはレスポンスヘッダーを確認して追加のパース処理が必要かどうかを判断するだけです

レスポンスヘッダー

X-Structured-Output-Degraded: <reason>

reason	意味
`model_unsupported`	当該モデル（または当該モデルの現在のプラットフォーム上）が構造化出力をサポートしていません
`json_object_unsupported_on_anthropic`	`json_object` モードは Anthropic フォーマットに変換できません
`json_schema_missing_schema`	`json_schema` タイプが指定されましたが `schema` フィールドがありません
`schema_keywords_stripped`	Schema 内の一部の制約キーワードがクリーニングされました（例：`minimum`、`maxLength`）

検出の例

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

# デグレードが発生したか確認
degraded = response.headers.get("X-Structured-Output-Degraded")
if degraded:
    print(f"構造化出力がデグレードされました：{degraded}")
    # この場合もモデルの応答は正常ですが、出力は Schema による強制制約を受けません
else:
    import json
    data = json.loads(response.json()["choices"][0]["message"]["content"])
    print(data)  # {"name": "John Smith", "age": 28}

`json_object` モードとの違い

	`json_schema`（構造化出力）	`json_object`
出力保証	指定された Schema に厳密に一致	有効な JSON であることのみ保証
フィールド制御	フィールド名、型、必須かどうかがすべて制約される	制約なし
対応プロトコル	OpenAI / Anthropic / Responses	OpenAI 互換プロトコルのみ
Claude 対応	`output_config.format` 経由	非対応

json_object モードは Claude ネイティブプロトコルへの変換をサポートしていません。OpenAI プロトコル経由で Claude に response_format: {"type": "json_object"} を送信した場合、レスポンスヘッダーに json_object_unsupported_on_anthropic のデグレードが記録されます。json_schema タイプの使用を推奨します。

よくある質問

どのモデルが Structured Outputs に対応していますか？

Claude シリーズ（Anthropic API の output_config.format 経由）：

Opus / Sonnet / Haiku 4.5 以降
Fable / Mythos 5 以降

OpenAI シリーズ（response_format 経由）：

GPT-4o 以降、GPT-5 シリーズ

Gemini シリーズ（responseSchema 経由）：

Gemini 2.5 以降

各モデルの対応機能タグはモデル一覧ページでご確認いただけます。

クロスプロトコル呼び出し時に JSON Schema は変更されますか？

はい。OpenAI プロトコル経由で Claude モデルを呼び出す場合、ゲートウェイが自動的に以下を実行します：

response_format を output_config.format に変換
Anthropic が非対応の Schema キーワード（minimum、maxLength 等）を除去
キーワードがクリーニングされた場合、レスポンスヘッダーに schema_keywords_stripped を記録

逆方向（Claude プロトコルから OpenAI モデルの呼び出し）も同様に自動変換されます。

Structured Outputs と Extended Thinking は同時に使用できますか？

はい。output_config 内の format（構造化出力）と reasoning 内の effort（思考強度）は独立したパラメータであり、同時に設定できます：

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

OpenRouter などの集約プラットフォームと比較して、デグレードメカニズムにはどのような違いがありますか？

多くの API 集約プラットフォームは、モデルが構造化出力をサポートしていない場合にエラーを直接返します。AIHubMix はグレースフルデグレード戦略を採用しています：互換性のないパラメータを自動的に除去し、モデルのレスポンスを正常に返した上で、X-Structured-Output-Degraded レスポンスヘッダーでクライアントにデグレードの理由を通知します。これにより、アプリケーションが中断されることはありません。

はじめに

ゲートウェイ機能

モデル機能

プロトコルリファレンス

プラットフォーム管理

プライバシーと利用規約

構造化出力 Structured Outputs

機能概要

各プロトコルのパラメータ対照表

クイックスタート

OpenAI プロトコル（推奨）

他のモデルの使用（GLM-5.2 の例）

Claude ネイティブプロトコル

Schema の記述ポイント

必須フィールド

ネストされたオブジェクト

クロスプロトコル間の Schema 差異

自動デグレードメカニズム

レスポンスヘッダー

検出の例

`json_object` モードとの違い

よくある質問

​機能概要

​各プロトコルのパラメータ対照表

​クイックスタート

​OpenAI プロトコル（推奨）

​他のモデルの使用（GLM-5.2 の例）

​Claude ネイティブプロトコル

​Schema の記述ポイント

​必須フィールド

​ネストされたオブジェクト

​クロスプロトコル間の Schema 差異

​自動デグレードメカニズム

​レスポンスヘッダー

​検出の例

​json_object モードとの違い

​よくある質問

機能概要

各プロトコルのパラメータ対照表

クイックスタート

OpenAI プロトコル（推奨）

他のモデルの使用（GLM-5.2 の例）

Claude ネイティブプロトコル

Schema の記述ポイント

必須フィールド

ネストされたオブジェクト

クロスプロトコル間の Schema 差異

自動デグレードメカニズム

レスポンスヘッダー

検出の例

`json_object` モードとの違い

よくある質問