响应格式 – ModelRiver Docs

ModelRiver 支持两种响应格式。默认情况下，系统返回 raw 格式，以最大程度兼容现有的 OpenAI / Anthropic 客户端。

Raw 格式（默认）

返回供应商的原始响应，保持与 OpenAI / Anthropic SDK 的完全兼容。

什么时候使用 raw 格式

直接替换现有 OpenAI / Anthropic 调用
不想修改客户端解析逻辑
需要最小传输开销和最简单的集成路径

元数据如何获取

在 raw 格式下，ModelRiver 会通过 HTTP Headers 返回元数据，例如：

X-ModelRiver-Provider
X-ModelRiver-Model
X-ModelRiver-Workflow
X-ModelRiver-Duration-Ms
X-ModelRiver-Attempts
X-ModelRiver-Cached-Data
X-ModelRiver-Offline-Fallback

Wrapped 格式

wrapped 格式会在原始响应外包一层额外信息，包含 ModelRiver 元数据、日志、缓存字段与回退信息。

什么时候使用 wrapped 格式

调试问题
监控供应商尝试与故障转移
访问 customer_data
构建内部控制台、管理后台或审计系统

wrapped 格式通常包含

data：原始 AI 响应
customer_data：从缓存字段中提取的业务上下文
meta：状态、耗时、使用的供应商、尝试次数等
logs：调试日志结构
backups：配置的备用供应商

选择建议

场景	推荐格式
OpenAI SDK 无缝替换	`raw`
内部后台 / 管理面板	`wrapped`
调试供应商回退	`wrapped`
对响应结构要求最少	`raw`
需要缓存字段与元数据	`wrapped`

使用示例

JavaScript（raw）

JAVASCRIPT

1const response = await fetch("https://api.modelriver.com/v1/ai", {
2  method: "POST",
3  headers: {
4    Authorization: "Bearer YOUR_API_KEY",
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    workflow: "my-chat-workflow",
9    messages: [{ role: "user", content: "Hello!" }],
10  }),
11});
12 
13const data = await response.json();
14console.log(data.choices[0].message.content);

cURL（wrapped）

Bash

curl -X POST https://api.modelriver.com/v1/ai \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "my-chat-workflow",
    "format": "wrapped",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

下一步

错误处理：理解 raw 与 wrapped 下的错误结构
API 端点：查看完整请求字段与返回值
可观测性：基于 wrapped 元数据构建监控与调试流程

raw 还是 wrapped：选择适合你的响应格式