快速开始 - Mirobody

第一次运行只需要 curl 和两条样例读数。你将写入读数，确认两者解析为相同的 LOINC 编码，并针对它们提问。建议预留约 10 分钟。示例数据保留一小时；真实数据请设置合适的留存期限。

准备工作

请在将要调用的同一区域创建 mb_live_* 密钥：中国区控制台或全球区控制台。打开 API Keys，在密钥出现时立即复制；它只显示一次。在终端设置对应的 API 地址和密钥。下面默认中国区；如果账户在全球区，改用注释中的全球区地址：

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

所有 /v1 接口共用一个 base URL，按你账户使用的集群选择：

https://api.mirobody.ai/v1   # 全球
https://api.mirobody.cn/v1   # 中国

以上是 Cloud 的集群。自部署不提供 /v1，它暴露的是自己的 /api/* 路由与一个 /mcp 端点，见自部署 Mirobody。日本与欧盟集群正在筹备中，见区域。模型提供方与定价可能因区域不同，请从实际调用的集群读取 GET /v1/models。

运行示例

① 收集：写入两条样例读数

健康数据有四种形态，每种形态各有一个写入端点：

数据形态	典型来源	录入方式	端点
结构化记录	首要是设备与可穿戴数据（由你自己接入，日聚合后写入），另有手动记录	结构化记录	`POST /v1/data`，高频样本先自聚合；episode 型（睡眠、运动）用 `time` + `end_time` 携带时段。见设备数据 cookbook。
文件/照片	化验单、体检报告 PDF、手机拍照	文件上传	`POST /v1/files`，保存原件、抽取文本，并自动抽出标准化读数。`POST /v1/standardize` 可同步执行同一抽取，例如做 dry-run 预览。
带读数的叙事	“头疼了一天，体温 38.2 °C”、对话口述	叙事文本	`POST /v1/standardize`，抽取其中的可量化读数，周边叙事被丢弃。
纯主观日记	“整个下午头晕头疼”、心情记录	单轮 agent 调用	`POST /v1/responses` 带 `store: true`，自动从中抽取读数与持久记忆。见写日记配方。

Mirobody 负责存储源数据、标准化结构化读数，并将二者提供给 AI 使用；数据如何采集、是否预处理，由你自行决定。用 POST /v1/data 写入结构化读数，retention 必填。下面每一步都使用相同的 user，保证操作的是同一个 Subject。

curl "$MIROBODY_API_BASE/data" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "user": "docs-demo",
        "retention": "1h",
        "records": [
          {"indicator": "fasting_glucose", "value": 97, "unit": "mg/dL", "time": "2026-06-16T07:30:00Z"},
          {"indicator": "FBG",             "value": 92, "unit": "mg/dL", "time": "2026-06-17T07:25:00Z"}
        ]
      }'

预期 JSON 响应包含 "status": "ok"、"ingested": 2 和 "subject": "docs-demo"；standardized 表示成功匹配 LOINC 编码的条数。重复执行会增加记录：写入不具备幂等性。user 是租户隔离键。在应用中为每位终端用户传入各自稳定、不同的 id。

② 转译：数据带着编码返回

注意上面的两种写法：fasting_glucose 和 FBG。把数据读回来，两行都带有同一个 LOINC 编码、规范名称和 UCUM 解析后的值：

curl "$MIROBODY_API_BASE/data?user=docs-demo&limit=10" \
  -H "Authorization: Bearer $MIROBODY_API_KEY"

{
  "object": "list",
  "data": [
    {
      "indicator": "FBG",
      "value": "92",
      "parsed_value": "92",
      "parsed_unit": "mg/dL",
      "loinc_code": "1558-6",
      "canonical_name": "Fasting glucose [Mass/volume] in Serum or Plasma",
      "time": "2026-06-17T07:25:00+00",
      "source": "api",
      "comment": ""
    },
    {
      "indicator": "fasting_glucose",
      "value": "97",
      "parsed_value": "97",
      "parsed_unit": "mg/dL",
      "loinc_code": "1558-6",
      "canonical_name": "Fasting glucose [Mass/volume] in Serum or Plasma",
      "time": "2026-06-16T07:30:00+00",
      "source": "api",
      "comment": ""
    }
  ],
  "has_more": false,
  "subject": "docs-demo"
}

对一个新 Subject，响应应包含两种名称，它们的 loinc_code 相同；ID 等其他字段可能变化。value 是字符串形式的原始数值，解析后的单位另列。这就是标准化管线：确定性的名称→LOINC（不让 LLM 猜码）+ UCUM，作用于每次结构化记录写入。

③ 智能体：获得有依据的回答

用相同的 user 调用问答 API。它可以查询刚写入的两条数据，包括名称为 FBG 的那条：

curl "$MIROBODY_API_BASE/chat/completions" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "mirobody-flash",
        "user": "docs-demo",
        "messages": [{"role": "user", "content": "What fasting glucose readings did I add?"}]
      }'

回答在 choices[0].message.content 中。health_records 和 message.tool_steps 能帮助你查看用到了哪些记录和服务端工具；具体内容每次可能不同。如果需要自己的工具或对话状态，请继续阅读智能体 API 和 SDK 示例。使用 agent SDK 时也要传入同一个 Subject，否则会读取账户默认 Subject。

调用失败时

遇到 401，先确认密钥与 MIROBODY_API_BASE 属于同一区域，再检查 Bearer 请求头；遇到 400，根据错误参考中的 error.code 和 error.param 定位字段；遇到 429，阅读限流与配额，区分速率限制与配额耗尽。

其他数据来源

化验报告可通过文件接口上传 PDF、照片或表格。想同步预览提取出的读数，可用 POST /v1/standardize 提交文件或已上传的 file_key。批量写入设备读数见结构化记录。这些路径都遵守相同的 user 隔离规则。

控制台演练场

控制台演练场采用相同流程：① 采集数据 → ② 自动标准化 → ③ agent 或问答。无需写代码即可上传文件、查看抽取文本或标准化记录，并试用两个 API。请打开与你账户同一区域的控制台，用量统计在其侧栏。

中国区演练场

适用于在 platform.mirobody.cn 创建的密钥。

全球区演练场

适用于在 platform.mirobody.ai 创建的密钥。

下一步

选择你的 API

Answers vs Agent：封闭问答还是完整 agent。

Agent API

客户端工具、存储的对话、流式事件。

标准化

OCR → 抽取 → LOINC → UCUM，一次讲透。

SDK 示例

curl / Python / Node / openai-agents 端到端。

​准备工作

​运行示例

​调用失败时

​其他数据来源

​控制台演练场