协议与接口
协议总览
ModelTown 对外提供的五种调用协议、各自的地址与认证方式，以及该选哪一种。
首版设计
网关正在开发中，本页描述的是首版对外接口设计，正式上线以公告为准。
对外协议与上游相互独立
你用什么协议调用 ModelTown，和 ModelTown 用什么方式调用上游（火山方舟、阿里云百炼，以及以后接入的其他供应商）是两件独立的事。网关负责在两边之间转换格式：
- 同一个模型可以用不同协议调用，例如
qwen3.8-max既能用 Chat Completions，也能用 Anthropic Messages。 - 以后增加或更换上游供应商，你的代码和配置不需要修改。
- 每个模型支持的协议，在 模型广场 可以按“协议”筛选，详情页的“协议”一节也会列出。
五种协议
| 协议 | 接口 | 适用模型 | 常见用途 |
|---|---|---|---|
| Chat Completions | POST /v1/chat/completions | 全部对话模型 | OpenAI SDK、LangChain、Dify、Cherry Studio 等绝大多数工具 |
| Responses | POST /v1/responses | 全部对话模型 | Codex、OpenAI Agents SDK |
| Anthropic Messages | POST /v1/messages | 全部对话模型 | Claude Code、Anthropic SDK |
| Embeddings | POST /v1/embeddings | 向量模型 | 语义检索、RAG 知识库入库 |
| Rerank | POST /v1/rerank | 重排序模型 | 对检索结果重新排序 |
地址与认证
| 协议 | Base URL | 认证请求头 |
|---|---|---|
| OpenAI 系（Chat Completions、Responses、Embeddings、Rerank） | https://api.example.cn/v1 | Authorization: Bearer <Key> |
| Anthropic Messages | https://api.example.cn（不带 /v1，SDK 会自动拼上 /v1/messages） | x-api-key: <Key>，也接受 Authorization: Bearer <Key> |
同一个 Key 可以调用所有协议。api.example.cn 为占位地址，正式域名上线后统一更新。
怎么选
- 不确定用哪个：选 Chat Completions，兼容的工具最多。
- 用 Claude Code：选 Anthropic Messages，见 Claude Code 接入。
- 用 Codex：选 Responses，见 Codex 接入。
- 做知识库检索：入库用 Embeddings，召回后用 Rerank 精排。
计费
三种对话协议按同一套价格计费，换协议不影响价格。向量、重排序模型只按输入 tokens 计费。详见 计费规则。