结构化输出修复

为 API Key 开启结构化输出修复：结构化输出请求返回的 JSON 存在截断、尾随逗号、代码块包裹等格式错误时，网关自动修复为可解析的合法 JSON，数值保持原样，支持 Chat Completions、Responses、Claude、Gemini，客户端零改动。

模型在结构化输出场景下返回的 JSON 有时无法通过解析：输出被 max_tokens 截断、带有尾随逗号、内容被包在 Markdown 代码块里。应用侧通常要为此编写重试或手工修复逻辑。

结构化输出修复（Structured Output Repair）是一个 Key 级别的能力，默认关闭。开启后，对声明了结构化 JSON 输出的非流式请求，当模型返回的 JSON 存在格式错误时，AIHubMix 网关在返回前自动将其修复为可解析的合法 JSON；客户端代码无需改动。

该开关默认关闭；未开启时所有响应原样返回。开关按 Key 独立配置，开启后立即生效。

前往 Key 管理页配置

创建或编辑 Key，打开「结构化输出修复」（Structured Output Repair）开关。

---

​

1. 生效条件

修复只在以下条件全部满足时发生：

1. 请求使用的 Key 已开启「结构化输出修复」。
2. 请求为非流式（未设置 stream: true）。
3. 请求声明了结构化 JSON 输出（各协议的声明字段见下表）。
4. 模型返回的文本内容无法通过 JSON 解析。

协议	端点	结构化输出声明字段
Chat Completions	/v1/chat/completions	response_format.type 为 json_object 或 json_schema
Responses	/v1/responses	text.format.type 为 json_schema 或 json_object
Claude Messages	/v1/messages	output_config.format.type 为 json_schema
Gemini	/gemini/v1beta/models/{model}:generateContent	generationConfig.responseMimeType 为 application/json，或设置了 responseSchema

内容本身是合法 JSON 时不做任何改动，原样返回。

---

​

2. 可修复的格式错误

输出截断导致括号 / 引号未闭合（如 finish_reason 为 length）：

修复前

{"items": [{"name": "Widget", "price": 9.99}, {"name": "Gad

修复后

{"items": [{"name": "Widget", "price": 9.99}, {"name": "Gad"}]}

Markdown 代码块包裹：

修复前

```json
{"status": "ok", "count": 3}
```

修复后

{"status": "ok", "count": 3}

尾随逗号：

修复前

{"a": 1, "b": 2,}

修复后

{"a": 1, "b": 2}

单引号：

修复前

{'name': 'Widget'}

修复后

{"name": "Widget"}

键名未加引号：

修复前

{name: "Widget", price: 9.99}

修复后

{"name": "Widget", "price": 9.99}

文本与 JSON 混杂（JSON 前后带说明文字）：

修复前

Here is the JSON you requested: {"name": "Widget", "price": 9.99}

修复后

{"name": "Widget", "price": 9.99}

修复采取保守策略：

• 修复只补全或规范化 JSON 语法；数值与字符串内容保持原文，不发生精度损失或改写。
• 修复产物必须是合法的 JSON 对象或数组，且与原文差异在合理范围内；任一条件不满足时放弃修复、原样返回原始内容。

---

​

3. 如何判断响应被修复过

发生修复时，有两个可编程 / 可查看的信号：

1. 响应头 X-JSON-Repaired: true（未发生修复时无此响应头）。
2. 调用日志备注：调用记录页 对应请求的备注列显示 This request gateway automatically corrected the JSON format issue in the model output.

Token 用量与计费按模型的原始输出计算，修复不改变计费结果。

---

​

4. 完整示例

以生成商品信息为例，请求使用 json_schema 声明结构化输出；开启开关后，即使模型输出存在上述格式错误，拿到的 content 也可以直接解析：

Python

import json
import os
import requests

response = requests.post(
    "https://aihubmix.com/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-5.2",
        "messages": [
            {"role": "user", "content": "Generate a product listing for a wireless keyboard."}
        ],
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "product",
                "schema": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "price": {"type": "number"},
                        "description": {"type": "string"},
                    },
                    "required": ["name", "price"],
                    "additionalProperties": False,
                },
            },
        },
    },
)

repaired = response.headers.get("X-JSON-Repaired") == "true"
product = json.loads(response.json()["choices"][0]["message"]["content"])
print(product, "repaired:", repaired)

const response = await fetch("https://aihubmix.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-5.2",
    messages: [
      { role: "user", content: "Generate a product listing for a wireless keyboard." },
    ],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "product",
        schema: {
          type: "object",
          properties: {
            name: { type: "string" },
            price: { type: "number" },
            description: { type: "string" },
          },
          required: ["name", "price"],
          additionalProperties: false,
        },
      },
    },
  }),
});

const repaired = response.headers.get("X-JSON-Repaired") === "true";
const data = await response.json();
const product = JSON.parse(data.choices[0].message.content);
console.log(product, "repaired:", repaired);

curl -sD - https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {"role": "user", "content": "Generate a product listing for a wireless keyboard."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "product",
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "description": {"type": "string"}
          },
          "required": ["name", "price"],
          "additionalProperties": false
        }
      }
    }
  }'

想主动观察一次修复，可以把 max_tokens 设置为较小的值（如 80）让输出被截断：响应的 finish_reason 为 length，content 是修复后的合法 JSON，响应头带有 X-JSON-Repaired: true。

---

​

5. 边界与说明

流式请求（stream: true）不做修复，按原样转发。需要修复能力时请使用非流式请求。

修复保证内容可以通过 JSON 解析；被截断而缺失的数据无法恢复。建议同时检查 finish_reason / stop_reason，输出被截断时按需增大 max_tokens 后重试。

• 语法修复：字段名、字段类型是否符合你的 schema 仍需应用侧校验。
• 工具调用参数不在修复范围：tool_calls / function_call 的参数 JSON 不做修复；工具参数在执行前应始终由应用侧校验。
• 多文本块输出不做修复：模型输出包含多个文本块（例如 Gemini 返回多个 parts）时按原样返回。
• 推理内容不受影响：reasoning_content、Gemini 的 thought 部分等推理文本不参与修复。

---

​

常见问题

修复会改变返回内容里的数值或文本吗？

不会。修复只补全或规范化 JSON 语法（补全闭合括号、去除尾随逗号、引号规范化、剥离代码块标记），数值与字符串内容保持模型输出原文。

开启开关会影响未声明结构化输出的普通请求吗？

不会。未声明 response_format 等结构化输出字段的请求，以及所有流式请求，响应均原样返回。

修复会额外计费或改变 token 用量吗？

不会。Token 用量与计费按模型的原始输出计算，修复过程不产生额外费用。

修复后的 JSON 一定符合我定义的 schema 吗？

修复保证内容可以通过 JSON 解析；字段名与字段类型是否符合 schema 取决于模型输出本身，建议应用侧继续保留 schema 校验。