Answers API（Chat Completions）

端点

POST /v1/chat/completions
Authorization: Bearer mb_live_*
Content-Type:  application/json

Answers API 是一个封闭式、有据可循的问答：一个问题进，一条有证据支撑的回答出。平台 agent 用服务端工具（此处不可增删）收集数据主体（Subject）的真实健康数据，然后返回单条干净的回答，外加可追溯的工具轨迹。设 stream: true 走 SSE。

它刻意保持封闭 —— 没有客户端工具、没有响应格式控制、没有多轮状态。这让它很容易嵌入：直接调用，或把它包成你自己 agent 里的一个工具。若你需要客户端工具、存储的对话或 previous_response_id 链式续聊，请使用 Agent API（POST /v1/responses）。

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

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

日本与欧盟集群正在筹备中 —— 见区域。模型提供方与定价可能因区域不同，请从实际调用的集群读取 GET /v1/models。

快速上手

curl https://api.mirobody.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "mirobody-flash",
        "messages": [{"role": "user", "content": "How is my fasting glucose trending?"}],
        "user": "alice"
      }'

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="mirobody-flash",
    messages=[{"role": "user", "content": "How is my fasting glucose trending?"}],
    user="alice",                                 # 租户隔离键（一个 Subject）
)
print(resp.choices[0].message.content)
# resp.choices[0].message.reasoning_content      # provider 返回的推理文本（可能为空）
# resp.choices[0].message.tool_steps             # 服务端工具轨迹：{id, name, arguments, result}

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MIROBODY_API_KEY,
  baseURL: "https://api.mirobody.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "mirobody-flash",
  messages: [{ role: "user", content: "How is my fasting glucose trending?" }],
  user: "alice",
});
console.log(resp.choices[0].message.content);

请求体

字段	类型	说明
model	string	mirobody-flash（默认）或 mirobody-expert。详见模型。
messages	array	OpenAI {role, content}。此面无状态 —— 每次调用需发送完整历史；system 消息用于设定语气/格式（见系统提示）。
stream	bool	true → SSE 流式返回 chat.completion.chunk 帧。
user	string	租户隔离键 → 一个 Subject。为每个终端用户传入其稳定 id。详见多租户。

注意

user 字段是租户隔离键。 后端把 (你的账户, user) 映射为内部的数据主体（Subject），Subject 之间完全隔离 —— 为每个终端用户传入其稳定 id，任何用户都看不到别人的数据。省略时回落到你账户的默认 Subject。Subject 对 Mirobody 网页应用和其他开发者均不可见。

该值在映射前会被归一化（去首尾空白 + 转小写），Alice 与 alice 解析为同一个 Subject。请传入稳定、规范的 id。

retention 与 session_id 不是这个无状态接口的字段。请在写入数据、文件或由 /v1/standardize 存储读数时设置留存策略；需要服务端对话状态时，请使用 Agent API。

不支持的参数

该接口是封闭式、有据可循的问答 —— 工具只在服务端运行，回答是自由文本。与此矛盾的参数会被显式拒绝并返回 400（code: unsupported_parameter，param 指出问题字段），而不是被静默吞掉：

参数	结果
tools、functions	400 unsupported_parameter —— 自带工具请走 Agent API
tool_choice、function_call	400 unsupported_parameter
response_format	400 unsupported_parameter —— 此面不提供结构化输出
n > 1	400 unsupported_parameter —— 永远只有单个 choice

注意

采样参数接受但忽略（agent 型接口的业界惯例）：max_tokens 不限制输出；temperature、top_p、stop、seed 无效。响应始终只含一个 choice。

注意

reasoning_effort 已生效（"low" | "medium" | "high"）：映射到底层模型的深度思考 / 推理预算。思考内容通过 delta.reasoning_content 流式返回，非流式响应中作为 message.reasoning_content 返回；usage.completion_tokens_details.reasoning_tokens 计入其 token。省略即为模型默认；无思考模式的模型会忽略它。

响应

message.content 只承载一条干净的最终回答。可选的 provider 推理文本与服务端工具调用走独立通道，不会混入工具叙述。

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1783741077,
  "model": "mirobody-flash",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "Your fasting glucose has trended down ~8% over the last 30 days ...",
      "reasoning_content": "",                                            // provider 返回的推理文本；可能为空
      "tool_steps": [                                                     // 服务端工具轨迹，按序
        { "id": "call_abc", "name": "query_health_data",
          "arguments": { "query": "fasting glucose last 90 days" },
          "result": "{...}" }
      ]
    }
  }],
  "usage": {
    "prompt_tokens": 12,                                                  // 只计你可见的输入
    "completion_tokens": 210,
    "total_tokens": 222,
    "prompt_tokens_details": { "system_tokens": 10096 },                  // 与可见 prompt_tokens 分开报告
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "billed_tokens": { "input": 20391, "output": 841, "total": 21232 }    // 实际计量的 token 总数
  },
  "health_records": [ { "tool": "query_health_data", "data": "..." } ],
  "citations": [ { "tool": "search_medical_evidence", "data": "..." } ]
}

通道	内容
message.content	只有最终回答（“回复”通道）。
message.reasoning_content	Provider 返回的推理文本。它可能为空，也不代表完整的模型内部推理。
message.tool_steps[]	服务端工具轨迹 —— 每条 {id, name, arguments, result}，按 id 合并。始终返回；没有开关参数，也没有截断开关。
health_records	回答所依赖的健康数据工具输出 —— {tool, data} 对。可解释性就在这里。
citations	外部医学证据工具（search_medical_evidence / read_source）的输出 —— {tool, data} 对；未查证据时为空。
usage	Token 计量 —— 见下文。

reasoning_content 和 tool_steps 是增量通道 —— 只读 message.content 的客户端不受影响。

用量口径

usage.prompt_tokens 只报告你实际发送的输入（你的 messages）；平台系统提示与工具 schema 单列在 prompt_tokens_details.system_tokens。completion_tokens_details.reasoning_tokens 报告 provider 的推理 token。计数为该 agent 轮次内所有模型调用之和。

usage.billed_tokens 是你被实际计量的 token 总数。按模型目录的标准输入/输出单价相乘可估算费用；提示词缓存折扣可能使实际计量费用更低。

流式传输

stream: true 时帧按序到达。首个 chunk 携带 delta.role: "assistant"（对齐 OpenAI —— 许多客户端以它初始化消息），随后是可选的推理/工具增量，最后是一条不间断的回答流：

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":""}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"reasoning_content":"<fragment>"}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"tool_steps":[{"id":"call_abc","name":"query_health_data","arguments":{...}}]}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"<answer fragment>"}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}],"health_records":[...],"citations":[...],"usage":{...}}
data: [DONE]

按 id 合并 tool_steps（流式步骤携带 {id, name, arguments}；完整 result 在非流式响应上）。最后一帧（[DONE] 之前）携带顶层 health_records / citations 以及 usage。上游失败会在流结束前以 SSE {"error": ...} 帧到达。只读 delta.content 的客户端不受影响。

系统提示

system 消息设定回答的语气、人设、格式与语言。服务端工具的可用范围与 Subject 隔离仍由平台控制；该提示不能获得其他 Subject 的访问权，也不能添加工具。

内置工具

除了普通的工具调用，托管 agent 还能规划多步工作、分派子任务、运行沙箱代码做数值分析（趋势、相关性），并读取 Subject 上传的文件。这些都不需要你调用 —— agent 自己会，基于该 Subject 的数据。

托管 agent 可调用的工具：

• query_health_data —— 检索并聚合 Subject 的记录
• list_clinical_records —— 列出临床文档 / FHIR 支撑的记录
• list_family_members —— 解析 Subject 有权查询的照护圈成员
• search_medical_evidence —— 检索文献、指南/共识与注册试验（供给 citations）
• read_source —— 按检索返回的 ref 读取一条结果；不支持任意 URL 抓取

/v1 agent 的主循环只读。存储对话中提到的健康事实会被自动抽取（见状态与记忆），而不是在回答过程中由工具写入。规划、分派与代码分析类工具属于内部实现，不属于 API 契约。ask_user 服务于网页应用，但在 /v1 接口上已禁用，因为 API 调用方没有可响应的交互组件。通过 /v1/files 上传的文件，处理完成后即可供 agent 读取。

要添加你自己的工具，请使用 Agent API 的 function calling —— 此面刻意不提供工具注入。

图表（vis-chart）

当回答涉及趋势 / 对比 / 分布时，可能嵌入一个围栏 ```vis-chart 代码块，内容为纯数据 JSON（{type, title, axisXTitle, axisYTitle, data}）。渲染是客户端的职责 —— API 只返回数据规格。检测该围栏块并渲染（折线 / 面积 / 柱状 / 饼图）。