Mirobody 的托管 API 兼容 OpenAI。把任意 OpenAI SDK 指向下方的 base URL，传入一个 mb_live_* 密钥，调用 /v1/chat/completions —— 智能体会基于每个终端用户真实、结构化的健康数据作答，并附带可追溯的引用。同一套引擎也可自行部署 —— 构建开源 C++ 引擎（./build.sh）并自己运行；托管 API 在其之上提供了托管存储、密钥与计费。
你在开发者控制台中创建密钥、查看用量、试用在线 Playground。本文档是 API 参考。
Base URL
Mirobody 采用全球优先架构。当前可用于集成对接的线上环境是全球测试集群 —— 请把你的 SDK 指向这里：
https://test-mirobody-api.thetahealth.ai/v1
https://mirobody-api.thetahealth.ai/v1）与中国生产 API（https://mirobody-api.thetahealth.cn/v1）仍在筹备中 —— 但中国测试环境（C 端应用 + 开发者控制台）现已上线。完整的主机矩阵与上线状态见区域。
每次调用都用 mb_live_* 密钥鉴权 —— 见鉴权。
| 接口面 | 方案 | 如何获取 |
|---|
/v1/*（API） | Authorization: Bearer mb_live_* | 在控制台 → API Keys 中创建密钥。密钥仅显示一次。 |
/api/console/*（控制台） | 会话 JWT（登录） | 在控制台中通过邮箱验证码或微信登录。 |
/v1 密钥不是 JWT —— 它们是与你的账户绑定的长期 API 密钥。切勿在客户端代码中携带它们。
OpenAI 兼容性
标准 OpenAI 字段可直接使用；Mirobody 扩展字段随 extra_body（Python SDK）携带，或作为顶层普通 JSON（curl/fetch）传入。
| 字段 |
|---|
| 标准 | model、messages、stream、user |
| Mirobody 扩展 | retention、session_id、health_context、mcp_servers、include_tool_steps |
| 响应 | choices[0].message.content（外加 reasoning_content、tool_steps）、usage，以及顶层 health_records / citations |
采样参数为兼容而被接受，但生成由智能体自行掌控。 max_tokens 会被接受但不强制生效 —— 输出长度由智能体控制。temperature、top_p、stop、seed 会被接受但忽略。n 取 1 以外的值同样不强制生效 —— 响应仍只返回单个 choice。
多租户：user 字段
每个请求都携带一个 user 字符串 —— 即多租户隔离键。后端将 (你的账户, user) 映射到一个内部数据主体(Subject)；你传入的每个 user 都与其他 user 完全隔离。把每个终端用户的稳定 id 作为 user 传入，他们的数据就永远不会互相串通。省略它，调用会回退到你账户的默认数据主体(Subject)。数据主体(Subject)不是消费者账户 —— 它们对 Mirobody 应用以及其他开发者都不可见。
数据留存
你提供的任何内容（结构化记录、上传文件、内联 health_context）都携带一个 retention，用于决定保留多久：
retention | 含义 | 生命周期 |
|---|
permanent | 保留至显式删除（内联 health_context 的默认值） | 永久 |
session | 绑定到 session_id，会话结束时丢弃 | ≤ 24h，或 DELETE /v1/sessions/{id} |
1d | 一天内自动删除 | ≤ 24h |
6h | 写入 6 小时后自动删除 | ≤ 6h |
2h | 写入 2 小时后自动删除 | ≤ 2h |
1h | 写入 1 小时后自动删除 | ≤ 1h |
none | 仅用于本次请求，永不持久化 | 在 finally 中删除 |
permanent（又名 persistent）| 1h | 2h | 6h | 1d | session | none。任何有时限的粒度都被硬上限限制为 ≤ 24h。
在 POST /v1/data 上 retention 字段为必填 —— 没有默认值；省略它会返回 400（code: invalid_retention）。对于 POST /v1/chat/completions 上的内联 health_context，其默认值为 permanent。
none 适用于内联 health_context（用完即弃）。在 POST /v1/data 上，none 会被拒绝并返回 HTTP 400（写入存储却要求不存储是自相矛盾的）—— 用完即弃的结构化数据请改为在 POST /v1/chat/completions 上以 health_context + retention=none 附带。智能体只会读取数据主体(Subject)当前未过期的数据。
回答是可解释、可核查的 —— 不是”听起来合理”，而是”这个结论来自你的那条记录”。当前的可追溯性由 health_records 承载（一个顶层数组，元素为 {tool, data} 对 —— 即回答所依据的实际工具输出）。citations 数组保留给 record:N 形式的引用，目前返回为空，因此请读取 health_records。
错误格式
错误使用 OpenAI 风格的信封结构：
{
"error": {
"message": "`retention` is required (days int or 'persistent').",
"type": "invalid_request_error",
"code": "invalid_retention",
"param": "retention"
}
}
type 始终为 invalid_request_error；code 与 param 用于定位具体问题。已观察到的（状态码, code）组合：
| HTTP | code | 何时 |
|---|
400 | invalid_retention（字段相关） | 请求格式错误 / 缺少必填字段 —— param 指明是哪个字段 |
401 | null | 缺少或格式错误的 Authorization 头 |
401 | invalid_api_key | 错误或已吊销的 mb_live_* 密钥 |
404 | — | 未知资源（如 file_key / session_id） |
429 | — | 速率限制 —— 详见速率限制 |
500 | internal_error | 意外的服务端故障 |
502 | — | 上游智能体错误 —— 通常是瞬时的，请退避后重试 |
端点一览
| 方法 | 路径 | 用途 |
|---|
GET | /v1/models | 列出能力档（mirobody-flash / mirobody-expert） |
POST | /v1/chat/completions | 兼容 OpenAI 的健康对话（流式、health_context、mcp_servers） |
POST · GET | /v1/data | 写入 / 读取结构化记录 |
POST · GET | /v1/files | 上传并解析文件（OCR / Excel）、列出、获取解析后的文本 |
DELETE | /v1/sessions/{id} | 结束会话（见注意事项 —— 会话记录清除尚未生效） |
GET·POST·DELETE | /api/console/keys | 管理 API 密钥（JWT） |
GET | /api/console/usage | 用量：请求数 / token / 费用（JWT） |
