Answers API（Chat Completions）

复制本页的 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/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   # 中国

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

快速上手

运行示例前，请设置与 MIROBODY_API_BASE 同一区域的密钥：

export MIROBODY_API_KEY="mb_live_..."

curl "$MIROBODY_API_BASE/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"
      }'

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MIROBODY_API_KEY"], base_url=os.environ["MIROBODY_API_BASE"])

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: process.env.MIROBODY_API_BASE,
});

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_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 只返回数据规格。检测该围栏块并渲染（折线 / 面积 / 柱状 / 饼图）。

另见

Agent API（Responses）：完整的 agent 接口，可用你自己的工具与存储状态。
把 Answers API 用作工具：把这个端点包成你自己 agent 里的一个工具。
流式传输：这个端点发出的 SSE 帧。

​端点

​快速上手

​请求体

​不支持的参数

​响应

​用量口径

​流式传输

​系统提示

​内置工具

​图表（vis-chart）

​另见

端点

快速上手

请求体

不支持的参数

响应

用量口径

流式传输

系统提示

内置工具

图表（vis-chart）

另见