文档

文档

API 端点与请求模式

通过统一的 ModelRiver 端点发送同步或异步 AI 请求。获取包含完整元数据的结构化响应。

基础配置

设置值
Base URLhttps://api.modelriver.com
主端点POST /v1/ai
异步端点POST /v1/ai/async
认证方式Authorization: Bearer mr_live_...
Content-Typeapplication/json

所有请求都需要有效的项目 API Key。你可以在项目设置中创建和管理密钥。

同步请求

标准请求会立即返回 AI 响应。适用于聊天机器人、搜索或任何对延迟敏感的实时场景。

端点： POST /v1/ai

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."}
],
"metadata": {
"audience": "enterprise customers"
}
}'

Python 示例

PYTHON
1import requests
2 
3response = requests.post(
4 "https://api.modelriver.com/v1/ai",
5 headers={
6 "Authorization": "Bearer mr_live_your_key",
7 "Content-Type": "application/json"
8 },
9 json={
10 "workflow": "marketing-summary",
11 "messages": [
12 {"role": "user", "content": "Summarise this week's launch."}
13 ]
14 }
15)
16 
17data = response.json()
18print(data["data"])

Node.js 示例

JAVASCRIPT
1const response = await fetch("https://api.modelriver.com/v1/ai", {
2 method: "POST",
3 headers: {
4 "Authorization": "Bearer mr_live_your_key",
5 "Content-Type": "application/json",
6 },
7 body: JSON.stringify({
8 workflow: "marketing-summary",
9 messages: [
10 { role: "user", content: "Summarise this week's launch." }
11 ],
12 }),
13});
14 
15const data = await response.json();
16console.log(data.data);

异步请求

对于耗时较长的任务（批处理、复杂工作流、事件驱动管道），请使用异步端点。它会立即返回任务 ID，结果则通过 WebSocket 或 webhook 发送。

端点： POST /v1/ai/async

Bash
curl -X POST https://api.modelriver.com/v1/ai/async \
-H "Authorization: Bearer mr_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"workflow": "batch-processor",
"messages": [
{"role": "user", "content": "Process this large document..."}
]
}'

异步响应（立即返回）

JSON
1{
2 "message": "success",
3 "status": "pending",
4 "channel_id": "550e8400-e29b-41d4-a716-446655440000",
5 "websocket_url": "ws://api.modelriver.com/socket",
6 "websocket_channel": "ai_response:550e8400-e29b-41d4-a716-446655440000"
7}

WebSocket 流程

  1. 使用你的 ws_token 连接到 WebSocket URL
  2. 加入频道 ai_response:{project_id}:{channel_id}
  3. 监听包含最终结果的 response 事件

提示： 使用官方 Client SDK 可以自动处理 WebSocket 连接、重连和进度追踪。

请求字段

字段必填说明
workflow✅已保存工作流名称。会覆盖 provider 和 model
provider❌供应商名称（不使用工作流时必填）
model❌模型名称（不使用工作流时必填）
messages✅聊天格式载荷：{role, content} 对象数组
temperature❌采样温度（0–2），透传给供应商
max_tokens❌响应中的最大 token 数
top_p❌Nucleus sampling 参数
stream❌设为 true 启用 SSE 流式返回（见 流式传输）
format❌"raw"（默认）或 "wrapped"（见 响应格式）
response_format❌结构化输出的 JSON Schema（也可使用工作流里的 schema）
structured_output_schema❌直接传入 JSON Schema，而不必先创建工作流
tools❌用于函数调用的工具定义数组
tool_choice❌模型如何使用工具（auto、none 等）
inputs❌工作流可访问的自由字段
metadata❌自定义元数据（会通过缓存字段回显）
context❌传递给供应商的附加上下文

响应载荷

同步响应（wrapped 格式）

JSON
1{
2 "data": { "summary": "..." },
3 "customer_data": { "metadata.audience": "enterprise customers" },
4 "meta": {
5 "status": "success",
6 "http_status": 200,
7 "workflow": "marketing-summary",
8 "requested_provider": "openai",
9 "requested_model": "gpt-4o-mini",
10 "used_provider": "openai",
11 "used_model": "gpt-4o-mini",
12 "duration_ms": 1420,
13 "usage": {
14 "prompt_tokens": 123,
15 "completion_tokens": 45,
16 "total_tokens": 168
17 },
18 "structured_output": true,
19 "attempts": [
20 {"provider": "openai", "model": "gpt-4o-mini", "status": "success"}
21 ]
22 },
23 "backups": [
24 {"position": 1, "provider": "anthropic", "model": "claude-3-5-sonnet"}
25 ]
26}

响应字段说明

字段说明
dataAI 生成的响应内容
customer_data从请求元数据中回显的缓存字段
meta.status"success" 或 "error"
meta.workflow处理该请求的工作流
meta.used_provider实际提供响应的供应商
meta.duration_ms端到端请求耗时（毫秒）
meta.usageToken 消耗明细
meta.attempts所有供应商尝试的数组（包括故障转移）
backups为该工作流配置的回退供应商

错误响应

当请求本身有效但供应商失败时，ModelRiver 会返回 200 并携带 error 对象。传输或认证问题则返回标准 HTTP 状态码（401、403、429、5xx）。

JSON
1{
2 "data": null,
3 "customer_data": {},
4 "error": {
5 "message": "Provider request failed",
6 "details": {"status": 504, "message": "Upstream timeout"}
7 },
8 "meta": {
9 "status": "error",
10 "http_status": 502
11 }
12}

下一步