叙事文本与报告

复制本页的 curl 示例前，先选择 Cloud 区域。需要认证的调用必须使用与密钥同一区域的地址。下方示例都使用 MIROBODY_API_BASE：

export MIROBODY_API_BASE="https://api.mirobody.cn/v1"  # 中国区账户
# export MIROBODY_API_BASE="https://api.mirobody.ai/v1" # 全球区账户：改用这一行

SDK 示例中如果写有全球区的完整地址，中国区账户须换成对应的中国区地址。参阅区域。

POST /v1/standardize
Authorization: Bearer mb_live_*

POST /v1/extract 是本端点的已弃用别名，仍可使用，请求与响应完全相同。

文档进，标准化指标出。 /v1/standardize 读取一份化验报告或健康文档，返回其中找到的每条读数，每条都匹配到 LOINC 编码、归一到 UCUM 单位（机制见标准化机制）。调用是同步的（一次请求、读数即返回），因此一份多页文档可能耗时数秒，请相应设置客户端超时。默认是 dry-run（store=false）：你获得标准化结果，什么都不持久化，零副作用。设 store=true（并给出 retention）则同时把这些读数经由与 POST /v1/data 相同的管线、作为记录写入 Subject 的存储。

store=true 不具备幂等性，重复同一次调用可能写入重复记录。请先用默认 dry-run 检查文档，超时后不要盲目重试。

请求

两种输入形态：

multipart/form-data：一个 file（PDF / 图片 / Excel / 纯文本；图片与 PDF 会 OCR），下表字段作为表单字段。
application/json：{"text": "..."}（原始报告文本）或 {"file_key": "..."}（已通过 /v1/files 上传的文件）。

字段	类型	说明
`file` / `text` / `file_key`	—	恰好一个来源。`file_key` 未知或无可抽取文本 → `404`。
`user`	string	本次调用所针对的 Subject。
`store`	bool	默认 `false`（dry-run）。`true` 时同时写入读数。
`retention`	string	`store=true` 时必填：与 `POST /v1/data` 同一枚举（`permanent` / `1h` / `2h` / `6h` / `1d` / `session`）。
`session_id`	string	`retention=session` 时必填。

user 字段是租户隔离键。 后端把 (你的账户, user) 映射为内部的数据主体（Subject），Subject 之间完全隔离：为每个终端用户传入其稳定 id，任何用户都看不到别人的数据。省略时回落到你账户的默认 Subject。Subject 对 Mirobody 网页应用和其他开发者均不可见。该值在映射前会被归一化（去首尾空白 + 转小写），Alice 与 alice 解析为同一个 Subject。请传入稳定、规范的 id。

Dry-run（默认）

curl "$MIROBODY_API_BASE/standardize" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -F "user=alice" \
  -F "file=@lab_report.pdf"

标准化并存储

curl "$MIROBODY_API_BASE/standardize" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "user": "alice",
        "text": "Fasting glucose 97 mg/dL (2026-07-01); LDL cholesterol 120 mg/dL",
        "store": true,
        "retention": "permanent"
      }'

响应

{
  "object": "extraction",
  "data": [
    {
      "indicator_raw": "Fasting glucose",
      "canonical_name": "Fasting glucose [Mass/volume] in Serum or Plasma",
      "loinc_code": "1558-6",
      "value_raw": "97",
      "parsed_value": "97",
      "unit_raw": "mg/dL",
      "unit_ucum": "mg/dL",
      "confidence": 0.82,
      "measured_at": "2026-07-01"
    },
    {
      "indicator_raw": "LDL cholesterol",
      "canonical_name": "Cholesterol in LDL [Mass/volume] in Serum or Plasma",
      "loinc_code": "2089-1",
      "value_raw": "120",
      "parsed_value": "120",
      "unit_raw": "mg/dL",
      "unit_ucum": "mg/dL",
      "confidence": 0.79,
      "measured_at": null
    }
  ],
  "stored": false,
  "stored_count": 0,
  "subject": "alice"
}

字段	说明
`data[]`	每条抽取到的读数一行。
`indicator_raw` / `value_raw` / `unit_raw`	文档原文怎么写的。
`canonical_name` / `loinc_code`	确定性 LOINC 解析（`null` = 无高置信编码，绝不给猜的）。
`parsed_value` / `unit_ucum`	解析后的数值（以字符串返回）+ UCUM 归一化单位。
`confidence`	LOINC 匹配的相似度分数（0–1）。
`measured_at`	文档中找到的时间戳（如有）。
`page`	读数所在的源页码（从 1 起）；多页文档时出现。
`abnormal`	来源携带的异常范围标记（如 `"H"` / `"L"` / `"高"`）；非空时出现。
`stored`	本次调用是否写入了存储（回显 `store`）。
`stored_count`	实际写入的读数条数（dry-run 时为 `0`）。
`dropped`	可选，顶层。被判为不合理（越界或乱码值）而丢弃的读数，至少有一条被过滤掉时出现，便于你查看哪些没有进入 `data`。
`note`	仅当 `data` 为空时出现：说明未找到可量化读数（见下）。

无可量化读数的叙事文本

/v1/standardize 返回的是可量化读数。纯叙事文本（「整个下午头晕头疼」）是明确声明的边界，不是错误：调用成功（200），返回空的 data 数组加一个 note：

{
  "object": "extraction",
  "data": [],
  "stored": false,
  "stored_count": 0,
  "subject": "alice",
  "note": "no quantifiable readings found in the text; for subjective/journal entries, send a single-turn POST /v1/responses with store:true instead"
}

混合文本按预期工作：「头疼了一天，体温 38.2 °C」 会抽出体温读数、丢弃叙事部分。 纯主观记录（journal）使用 Agent API，没有专用端点。 把每条记录作为单轮 POST /v1/responses 发送，带 store: true、独立的 session_id（如 journal-{entry_id}）、builtin_tools: "none"，以及要求简短确认的 instructions。随后 Mirobody 会自动从这条已存储的记录中抽出可量化读数与持久记忆。采用每个 session_id 一个响应的设计时，删除该响应也会一并撤回它产生的记忆；已写入数据面的读数仍需通过 /v1/data 删除。准确生命周期见写日记。

错误

HTTP	何时
`400`	没有 `file` / `text` / `file_key`；`store=true` 但 `retention` 缺失或非法；`retention=session` 缺 `session_id`
`404`	`file_key` 未知或无可抽取文本
`413`	文件超出上传大小上限
`422`	无法从文件抽取文本
`502`	抽取模型不可用，瞬态；退避重试

所有失败都是显式的，不存在静默的部分成功。

另见

标准化机制：这个端点同步执行的那条管线。
结构化记录：直接写入结构化读数。
文件 / 照片：改为上传原始文档。

​请求

​Dry-run（默认）

​标准化并存储

​响应

​无可量化读数的叙事文本

​错误

​另见

请求

Dry-run（默认）

标准化并存储

响应

无可量化读数的叙事文本

错误

另见