ModelRiver 支持 OpenAI Chat Completions 协议，因此为其他 OpenAI 兼容网关编写的代码大多可以继续使用原来的 SDK。变化在于路由配置放在哪里。其他网关通常在 model 中接收供应商模型（如 openai/gpt-4o），并把路由规则放在请求体、请求头或配置文件中。在 ModelRiver 中，model 是一个工作流的名称，由工作流保存主模型、最多两个备用模型、结构化输出、防护规则、预算以及发布历史。
本页是技术参考。按平台的对比概览请参阅迁移到 ModelRiver。
代码中需要修改的内容
只需修改三个值。请求中的其他内容（messages、temperature、max_tokens、tools、stream）保持不变。
| 设置 | 迁移前 | 迁移后 |
|---|---|---|
| Base URL | 原网关的地址 | https://api.modelriver.com/v1 |
| API key | 原网关的密钥 | ModelRiver 项目密钥 mr_live_… |
model | 供应商模型、预设或别名 | 工作流名称，例如 support_bot |
切换之前，请先创建工作流，并把你的供应商密钥添加到项目中。创建工作流时会发布它的第一个 Live 版本，因此可以立即调用。工作流名称由字母、数字和下划线组成。
概念对照
| 你现在使用的 | 在 ModelRiver 中 |
|---|---|
model 中的 provider/model 字符串（如 openai/gpt-4o） | 工作流的主模型。改为发送工作流名称 |
| 请求中的回退模型列表 | 工作流的备用 1 和备用 2。ModelRiver 先尝试主模型，再依次尝试备用模型 |
| 保存的预设、虚拟模型或别名 | 一个工作流。编辑并发布新版本时，你发送的名称保持不变 |
| 放在请求头中的路由配置 | 请求中无需携带。路由由工作流保存 |
| 存放在网关中的供应商密钥 | 存放在 ModelRiver 项目中的供应商密钥（BYOK）。供应商直接向你计费，ModelRiver 不加收 token 费用 |
| 带版本的配置或预设历史 | 支持回滚的 Draft 与 Live 版本发布 |
response.model 显示供应商模型 | response.model 是工作流名称；实际作答的供应商和模型见响应头 |
| 在多个密钥或加权目标之间负载均衡 | 目前没有对应功能。工作流先运行主模型，仅在失败时切换到备用模型 |
| 预付额度或所有供应商合并成一张账单 | 没有对应功能。各供应商分别向你自己的账户计费 |
Responses API（/v1/responses） | 不支持。请使用 Chat Completions，见 OpenAI 兼容性 |
一个工作流包含一个主模型和最多两个备用模型。如果你的回退列表更长，请保留最常依赖的三个。
按网关的迁移前后对比
各网关的迁移前后代码示例目前仅提供英文版，请切换到本页的英文版本查看。下面按配置方式说明映射思路。
在 model 中填写 provider/model，并在请求中附带回退列表
本节的代码示例仅提供英文版。映射方式：主模型和回退列表中的模型分别填入工作流的主模型、备用 1 和备用 2，然后在 model 中发送工作流名称。若调用的是保存的预设，则用预设中的模型创建工作流。
通过 SDK 的提供方选项配置回退或虚拟模型
本节的代码示例仅提供英文版。映射方式：把回退模型或虚拟模型的配置重建为一个工作流，然后在 model 中发送工作流名称。SDK 设置见 OpenAI 兼容性；如果 SDK 默认调用 Responses API，请改为 Chat Completions。
通过请求头传递路由配置
本节的代码示例仅提供英文版。映射方式：配置中的每个目标对应工作流的一个模型槽位，迁移后不再需要额外的请求头。引用已保存的配置 ID 时，把该配置映射为一个工作流。
自托管代理与 config.yaml 中的别名
本节的代码示例仅提供英文版。映射方式：每个带回退的别名对应一个工作流，配置文件中的供应商密钥改为添加到 ModelRiver 项目。别名中常含连字符：support-bot 仍会解析到名为 support_bot 的工作流，但请发送准确名称。
查看实际运行的模型
响应中的 model 始终是工作流名称。要查看实际作答的供应商和模型，请读取响应头：
| 响应头 | 值 |
|---|---|
x-modelriver-workflow | 处理该请求的工作流 |
x-modelriver-revision | 实际运行的工作流版本号 |
x-modelriver-model-resolved-from | 当你发送的名称被解析为另一种写法时，显示原名称（如 support-bot → support_bot） |
x-modelriver-provider | 实际作答的供应商 |
x-modelriver-model | 实际作答的供应商模型；由备用模型作答时为备用模型 |
curl -si https://api.modelriver.com/v1/chat/completions \ -H "Authorization: Bearer $MODELRIVER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "support_bot", "messages": [{"role": "user", "content": "Hi"}]}' \ | grep -i '^x-modelriver-'请求日志会显示每个请求的每一次尝试，包括发生故障转移的尝试。
常见的首批错误与解决方法
如果 model 的值与任何工作流都不匹配，会返回 404，code 为 "model_not_found"，并附带一个 modelriver 对象，说明原因并推荐工作流。SDK 抛出的错误信息与此相同。错误信息为英文。
1{2 "error": {3 "message": "'openai/gpt-4o' is a provider model. ModelRiver's model field takes a workflow name; the workflow picks provider, model and fallbacks. Create one in Console → Workflows. List yours: GET /v1/models",4 "type": "invalid_request_error",5 "param": "model",6 "code": "model_not_found",7 "modelriver": {8 "reason": "provider_model",9 "suggestions": [],10 "docs_url": "https://modelriver.com/docs/api/gateway-migration"11 }12 }13}reason | 示例错误信息 | 解决方法 |
|---|---|---|
provider_model | 'gpt-4o' is a provider model. ModelRiver's model field takes a workflow name. Workflow 'support_bot' in this project runs openai/gpt-4o — send model="support_bot". | 发送推荐的工作流名称；没有推荐时，用该模型创建工作流 |
near_miss | Workflow 'suport_bot' not found. Did you mean 'support_bot'? Names use letters, digits and underscores. | 修正拼写 |
near_miss（大小写） | Workflow 'Support_Bot' not found. Names are case-sensitive — did you mean 'support_bot'? | 大小写须完全一致 |
ambiguous | 'my-wf' matches more than one workflow: 'my_wf', 'mywf'. Send the exact name. | 发送列出的其中一个名称 |
unknown | Workflow 'x' not found. This project has: a, b, c (+N more — GET /v1/models). | 检查 API key 所属项目，或选择列出的名称 |
missing_live | Workflow 'support_bot' has no Live version. Publish it in Console → Workflows. | 发布该工作流 |
none_callable | No workflow in this project accepts completion requests. Create a completion workflow in Console → Workflows. | 创建请求类型匹配的工作流 |
no_workflows | This project has no workflows yet. In ModelRiver, model is a workflow name, not a provider model. Create a workflow in Console → Workflows, then send its name. | 创建你的第一个工作流 |
另外两个常见错误：
401，响应体为{"error": "Invalid or missing API key"}：请求仍携带旧网关的密钥，或请求头不是Authorization: Bearer mr_live_…。该响应体是普通字符串，而不是 OpenAI 错误对象。POST /v1/responses返回404：你的 SDK 正在调用 Responses API。请改用 Chat Completions，各 SDK 的设置方法见 OpenAI 兼容性。
GET /v1/models 会列出你可以发送的名称。其他状态码见错误处理。
安全切换
- 把你的供应商密钥添加到 ModelRiver 项目。
- 为每个预设、别名或回退列表创建一个工作流，并在测试模式或 Playground 中运行。
- 在一条代码路径中修改 base URL、API key 和
model。 - 在确认无误之前，把当前网关保留在代码中作为回退，之后再移除。
- 以 Draft 形式编辑工作流，准备好后发布为 Live。需要时可在 History 中回滚。
下一步
- OpenAI 兼容性：端点、
/v1/models与 SDK 设置 - 构建工作流：主模型、备用模型、结构化输出与预算
- 版本发布：Draft、Live 与回滚
- 迁移到 ModelRiver：迁移概览