与官方接口的差异

页面组织

• 每个接口一页，页内固定三段：先一段总述，再用打勾表格列出支持清单，最后逐条说明与官方的差异——每条都附会触发它的请求和实际返回的样例。
• Chat（/v1/chat/completions）、Messages（/v1/messages）、Responses 平台函数（/v1/responses，含 WebSocket 传输）。
• 本页记录三个接口共用的规则：模型名称的填法、请求与错误的格式、推理控制、不同模型的行为差别。

model 填什么

请求里的 model 填平台对外开放的模型名称，就是控制台里看到的模型名，不是模型厂商的原始模型名。可用列表以 GET /v1/models 返回为准：

curl https://api.model-r.com/v1/models \
    -H "Authorization: Bearer mr-…"

返回

{
  "object": "list",
  "data": [
    { "id": "your-model", "object": "model", "owned_by": "franca" }
  ]
}

请求里的 model 就填这里返回的 id。

请求体上限

请求体超过 16MB 返回 413，报错里注明实际生效的上限。带图片的长会话一般不会撞到这个上限。详见错误码页的 request_too_large。

错误响应的统一格式

错误响应沿用各接口官方的错误格式，在此之上统一加两样东西：顶层的 request_id（本次请求的编号，报障时提供它），以及 error 里的 doc 字段（有细粒度错误码时，指向错误码页的对应条目）。

返回（Chat 形状的例子，漏了 model 字段）

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_parameter",
    "param": "model",
    "message": "Missing 'model'"
  },
  "request_id": "req-…"
}

模型服务对请求本身的拒绝（HTTP 400 / 422）原样透传：message 是模型服务的原文。

token 用量

• 用量由平台计量，不依赖模型返回：Chat 在流末按官方语义补一个 usage 块（开关是 stream_options.include_usage）；Messages 的响应带 usage 字段；Responses 在终态事件里带 usage。
• 控制台的用量明细和计费都按实际用量入账，不按请求里的声明。

在请求里声明 MCP 服务器（不支持）

Messages 和 Responses 都拒绝在请求里声明远程 MCP 服务器，在任何处理之前就返回 400。连接哪个服务器、用什么凭证是平台的配置，不该由调用方在每次请求里指定。

请求

{
  "model": "your-model",
  "input": "搜索一下今天的新闻",
  "tools": [
    {
      "type": "mcp",
      "server_label": "docs",
      "server_url": "https://mcp.example.com/sse"
    }
  ]
}

返回

{
  "error": {
    "type": "invalid_request_error",
    "message": "Client-declarable MCP tools are not supported; hosted tools are defined server-side (docs/unsupported-features.md)"
  },
  "request_id": "req-…"
}

Messages 的 mcp_servers[] 与 mcp_toolset 同样拒绝，报错相同。要搜索、执行代码这类能力，按官方格式声明托管工具（如 web_search）即可：工具在平台侧执行、按调用次数计费（见计费规则）；调用预算用顶层的 max_tool_calls 控制，Messages 与 Responses 同一种写法。

推理控制（三个接口共用）

「让模型思考多少」统一成七个档位：minimal / low / medium / high / xhigh / max，外加 none 表示关闭。三个接口用各自的官方字段表达它：Chat 用 reasoning_effort，Messages 用 output_config.effort 或 thinking，Responses 用 reasoning.effort。与官方的差别：

• 关闭思考：Responses 接受 reasoning.effort: "none"（官方枚举之外的扩展取值）；Messages 用官方的 thinking: {"type": "disabled"}。DeepSeek / Qwen 文档里的 thinking、enable_thinking 字段发到 Responses 会被忽略。
• Messages 的 thinking.budget_tokens 换算成档位发给模型（原始数值保留，响应回显时逐字还原）；换算表如下。
• 档位之外的取值（如自定义字符串）既不报错也不悄悄降级：交给部署方注册的思考阶段处理；没有注册时请求以可读错误失败，并列出全部合法档位。
• 必须思考的模型：显式关闭返回 400（reasoning_off_unsupported）；模型不支持的档位同样 400（reasoning_effort_unsupported）。都是平台发出的可读错误，不是模型服务的原始报错。

不同模型的行为差别

平台接入多家模型，思考控制与工具选择上行为不一，以下差别会体现在响应里。

• 关闭思考的有条件遵守：个别模型（实测 GLM 系列）只在请求带工具时遵守关闭声明，无工具时照常思考，按实际用量计费。平台不改写请求做补偿。
• 强制工具选择的降级：个别模型不支持 tool_choice 的 required 与命名函数写法，路由可配置降级为 auto 并在消息末尾追加一条指令。降级是尽力而为：模型仍可能用纯文本回答，客户端收到的是正常的文本响应，不是错误。
• 支持的档位因模型而异：某模型只支持 low / high 时，发 medium 会在发出前被平台以 reasoning_effort_unsupported 拒绝，不会变成模型服务的模糊报错。