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

# 结构化输出

> text.format —— 在 backbone 模式下把模型输出约束为 JSON（json_object）或 JSON Schema（json_schema）。

在 [`POST /v1/responses`](/zh/api-reference/responses) 上用 `text.format` 把模型输出强制为 JSON。它遵循 [OpenAI Responses `text.format` 规范](https://platform.openai.com/docs/api-reference/responses/create#responses-create-text)，**仅在 [backbone 模式](/zh/api-reference/backbone-mode)（`mode:"model"`）下可用**。

<Warning>
  `text.format` 需要 `mode:"model"`。在默认的 agent 模式下它返回 `400 unsupported_parameter`（`param: "text"`）—— 自由文本在下游爆炸比接口报错贵得多。Answers API（`/v1/chat/completions`）同样以 `400` 拒绝 `response_format`。
</Warning>

## `json_object`

把输出约束为语法合法的 JSON 对象（无 schema）：

```jsonc theme={null}
{
  "model": "mirobody-flash",
  "mode": "model",
  "input": "Reply with a JSON object having keys a and b.",
  "text": { "format": { "type": "json_object" } }
}
```

消息文本是一个由你自行解析的 JSON 字符串：

```jsonc theme={null}
{ "output_text": "{\"a\":1,\"b\":2}", "status": "completed", ... }
```

## `json_schema`

把输出约束为你提供的 schema。设 `strict: true` 要求严格贴合 schema：

<CodeGroup>
  ```bash curl theme={null}
  curl https://mirobody-api.thetahealth.ai/v1/responses \
    -H "Authorization: Bearer $MIROBODY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "mirobody-flash",
          "mode": "model",
          "input": "Give me a manifest for apples with count 3.",
          "text": {
            "format": {
              "type": "json_schema",
              "name": "manifest",
              "strict": true,
              "schema": {
                "type": "object",
                "properties": {
                  "item":  { "type": "string" },
                  "count": { "type": "integer" }
                },
                "required": ["item", "count"],
                "additionalProperties": false
              }
            }
          }
        }'
  ```

  ```python Python (OpenAI SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(api_key="mb_live_...", base_url="https://mirobody-api.thetahealth.ai/v1")

  resp = client.responses.create(
      model="mirobody-flash",
      extra_body={"mode": "model"},
      input="Give me a manifest for apples with count 3.",
      text={
          "format": {
              "type": "json_schema",
              "name": "manifest",
              "strict": True,
              "schema": {
                  "type": "object",
                  "properties": {"item": {"type": "string"}, "count": {"type": "integer"}},
                  "required": ["item", "count"],
                  "additionalProperties": False,
              },
          }
      },
  )
  print(resp.output_text)   # {"item":"apples","count":3}
  ```
</CodeGroup>

## Provider 降级

`text.format` 透传给底层模型。当背后的 provider **没有**原生 `json_schema` 支持时，Mirobody 会自动**降级重试一次** —— 用 `json_object` + 把 schema 注入系统提示。该重试对你透明（你仍拿到符合 schema 形状的 JSON），因此无需关心某个档位背后是哪个 provider，都可把结构化输出当作可靠能力使用。

## 另见

* [Backbone 模式](/zh/api-reference/backbone-mode) —— `mode:"model"`，`text.format` 的前置条件。
* [Function calling](/zh/api-reference/function-calling) —— 需要约束工具参数时，把 `text.format` 与 `tool_choice:"required"` 搭配使用。