协议兼容与差异

区分 Chat Completions、Responses 与 Anthropic Messages 的接入边界，以及网关转换协议时的差异。

网关按各家的原生协议提供接口：把官方 SDK 的根地址换成下表的地址、密钥换成 MossHub 密钥即可。支持某个入口不代表所有模型和参数都等价可用；一个模型能走哪些接口，看控制台模型详情的「接入」。

协议	SDK 的根地址
OpenAI（对话、Responses、图片、向量）	`$MOSSHUB_API_BASE/v1`
Anthropic Messages	`$MOSSHUB_API_BASE`
Gemini `generateContent`	`$MOSSHUB_API_BASE`
火山方舟（图片、视频任务）	`$MOSSHUB_API_BASE/ark/api/v3`
MiniMax（语音、视频任务）	`$MOSSHUB_API_BASE/minimax`

三种对话入口

入口	消息字段	输出方式
`POST /v1/chat/completions`	`messages`	普通 JSON 或 SSE
`POST /v1/responses`	`input` 与 `instructions`	Responses 结构及对应流事件
`POST /v1/messages`	`messages` 与独立 `system`	Anthropic 结构及对应流事件

POST /v1/messages/count_tokens 原样转给上游，不计费，也不做协议转换。

三种入口都使用平台密钥和 /v1/models 返回的模型 ID。不要把官方模型名称、上游的模型名和平台 ID 混为一谈。

模型原生支持所调用的协议时，请求体原样转给上游，只把顶层 model 换成上游的模型名；Chat Completions 的流式请求会补上 stream_options.include_usage 用于计量，客户端自己没要求时，这个用量块不会返回。temperature、tools、response_format 等参数由上游处理，不能据此认为所有模型都支持；模型能否读图，看 /v1/models 中的 capabilities.image_input。顶层字段重复的请求体返回 400。

请求头只转发 Content-Type、Accept、User-Agent、Anthropic-Version、Anthropic-Beta 和 OpenAI-Beta；/v1/messages 没带 anthropic-version 时，网关补上 2023-06-01。上游的 Retry-After、Retry-After-Ms、X-Should-Retry 与 anthropic-ratelimit-unified-* 响应头会返回给客户端。

网关转换协议时

模型没有原生的 Responses 或 Messages 接口时，网关会转换：/v1/responses 依次改走模型的 Anthropic Messages、Chat Completions 接口，/v1/messages 依次改走模型的 Responses、Chat Completions 接口。/v1/chat/completions 不做转换，模型没有这个接口时返回 400。

转换后，响应、流事件和错误仍按你调用的协议返回。响应带 X-Mosshub-Translated 头，值为上游协议，如 anthropic_messages；下表标为「丢弃」的字段出现时，X-Mosshub-Dropped 用逗号列出它们，标为「忽略」的不列出。

Responses

情况	处理
`previous_response_id`、`conversation`、`store: true`	返回 `400`：网关不保存响应，请带上完整上下文，`store` 设为 `false`
`background: true`	返回 `400`：只支持前台调用
`max_output_tokens`	没传时取模型的最大输出，目录没有标注时为 64000
`text.format` 要求 JSON 输出	返回 `400`：转换路径不支持结构化输出
`function` 工具	转成上游的函数工具，由调用方执行
`custom` 工具	转成只有一个字符串参数 `input` 的函数工具
其他工具，如 `web_search`、`file_search`、`code_interpreter`、`mcp`、`image_generation`	丢弃
`tool_choice`	只支持 `auto`、`none`、`required` 或指定一个工具，其他返回 `400`；`required` 或指定工具时关闭推理
`reasoning.effort`	映射为上游的推理强度；开启推理时丢弃 `temperature` 和 `top_p`
图片与文件	图片用 `image_url`（网址或 base64 数据 URL）；文件只支持以 `file_data` 内联的 PDF；带 `file_id` 返回 `400`
`metadata`、`user`、`service_tier`、`truncation` 等	忽略
其他无法对应的字段	丢弃

Anthropic Messages

字段	处理
`system`、`messages`、`tools`、`tool_choice`、`max_tokens`、`stream`	转成上游的对应字段
`thinking`	映射为推理强度：`budget_tokens` 小于 4096 为低，不少于 16384 为高，其余为中；带 `output_config.effort` 时以它为准
`temperature`、`top_p`、`stop_sequences`	改走 Chat Completions 时保留，`stop_sequences` 对应 `stop`；改走 Responses 时丢弃
带 `type` 的工具（`custom` 除外），如网页搜索	丢弃
图片与文档	图片用 base64 或网址，文档用 base64 内联；不能引用已上传的文件
`metadata`、`service_tier`	忽略
`top_k` 等其他字段	丢弃

上一轮返回的推理内容原样带回即可延续：Responses 在 include 里请求 reasoning.encrypted_content 后，推理放在 encrypted_content；Messages 放在 thinking 块里。它只在同一个上游模型上还原，改走 Chat Completions 时不保留推理。

Messages 的流式事件采用 message_start、content_block_delta、message_stop 等，转换时上游 15 秒没有输出会补发 ping。不要用 Chat Completions 的 [DONE] 解析器直接读取这类流。

媒体与向量不是普通对话

向量：POST /v1/embeddings，OpenAI Embeddings 格式，同步返回向量。
图片：OpenAI Images（/v1/images/generations、/v1/images/edits）、火山方舟（/ark/api/v3/images/generations）和 Gemini（/v1beta/models/{模型 ID}:generateContent）三种格式，都同步返回完整结果，不支持流式和 tools。
视频：沿用 MiniMax 和火山方舟的异步任务接口：提交任务、查询状态，成片从结果里的地址下载；不支持 callback_url，需要轮询。
语音：POST /minimax/v1/t2a_v2，MiniMax 格式，可以流式；上游的错误可能以 HTTP 200 返回，要检查 base_resp.status_code。

遇到差异时

网关不保证各家新增的参数都能转换。遇到差异请保留模型 ID、接口路径、响应头 X-Request-Id、X-Mosshub-Translated 与 X-Mosshub-Dropped，以及脱敏后的响应。