文档

文档

统一 AI 网关 API

通过一个高性能统一端点连接任意 LLM 供应商，自动处理模型故障切换、结构化 JSON 输出和 Token 跟踪。

面向所有 AI 供应商的单一 API

ModelRiver 提供一个统一 API 端点，可将请求路由到任意已配置的 AI 供应商，例如 OpenAI、Anthropic、Mistral、Google、xAI 等。你不再需要分别维护多个供应商集成，只需在控制台中配置 workflows，然后调用一个端点即可。其余工作由 ModelRiver 处理：供应商路由、自动故障切换、Token 跟踪和结构化输出校验。

工作方式

  1. 在 ModelRiver 控制台中创建工作流：选择供应商、模型、回退策略和输出 Schema
  2. 使用工作流名称向统一端点发送请求
  3. 以标准 OpenAI 格式接收响应，并包含使用了哪个供应商、消耗了多少 Token 等元数据
Bash
curl -X POST https://api.modelriver.com/v1/ai \
-H "Authorization: Bearer mr_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"workflow": "marketing-summary",
"messages": [
{"role": "user", "content": "Summarise this week's launch."}
]
}'

核心概念

将工作流作为模型别名

API 请求中的 workflow 字段会映射到 ModelRiver 控制台中的一个命名配置。每个工作流都可以指定：

  • 主供应商和模型，例如 openai/gpt-4o
  • 自动故障切换使用的回退供应商
  • 自动附加到每个请求前的系统指令
  • 用于保证 JSON 结构稳定的结构化输出 Schema
  • 在响应中回显请求元数据的缓存字段

你可以在控制台中更换供应商、模型或提示词，而不需要改应用代码。

两种 API 形式

ModelRiver 提供两种发送 AI 请求的方式：

功能原生 APIOpenAI 兼容 API
端点POST /v1/aiPOST /api/v1/chat/completions
认证Bearer mr_live_...Bearer mr_live_...
模型字段workflow 名称model = 工作流名称
响应原始格式或包装格式标准 OpenAI 格式
适用场景使用全部特性作为 SDK 的无缝替代

API 分区

端点与请求

基础配置、同步与异步请求模式、可选字段，以及完整响应负载说明。

OpenAI SDK 兼容性

把 ModelRiver 当作 OpenAI API 的直接替代。可接入任意兼容 OpenAI 的 SDK，例如 Python、Node.js、LangChain、LlamaIndex、Vercel AI 等。

流式传输

使用实时 Server-Sent Events（SSE）逐 Token 返回内容，包含心跳支持、超时处理，以及 Python 和 Node.js 示例。

函数调用

兼容 OpenAI 的 tools 与 tool_choice 用法。你可以传入函数定义、接收结构化 tool_calls，并处理多轮工具调用对话。

请求类型

为聊天补全、文本补全、图像生成、Embedding、音频处理和视觉分析等场景配置工作流。

响应格式

可在原始格式（OpenAI 兼容，适合生产）和包装格式（包含更多元数据，适合调试和分析）之间选择。

错误处理

查看标准错误结构、HTTP 状态码、常见错误码，以及生产环境中的重试与容错建议。

认证

了解 API Key 管理、请求头配置、密钥轮换和生产环境安全实践。

迁移指南

提供从 OpenAI、Anthropic 或其他供应商 API 迁移到 ModelRiver 的分步说明。

快速索引

我想要...前往
发送第一条请求端点
使用 OpenAI Python SDKOpenAI 兼容性
实时流式返回 Token流式传输
使用函数调用函数调用
生成图片或 Embedding请求类型
选择原始或包装响应响应格式
更稳妥地处理错误错误处理
轮换或保护 API Key认证
从 OpenAI 迁移迁移指南

下一步