身份验证与 API 密钥 – ModelRiver Docs

所有 ModelRiver API 请求都必须使用项目 API 密钥进行认证。密钥绑定到具体项目，并决定你可以访问哪些工作流、供应商与数据。

API 密钥格式

所有 API 密钥都使用 mr_live_ 前缀。创建密钥时，你可以选择过期时间：1 天、7 天、30 天、60 天、90 天或永不过期。开发环境建议使用短期密钥，生产环境使用更长有效期。

使用 API 密钥

Header 认证

在 Authorization 请求头中加入 API 密钥：

Bash

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

配合 OpenAI SDK

PYTHON

1from openai import OpenAI
2 
3client = OpenAI(
4    base_url="https://api.modelriver.com/v1",
5    api_key="mr_live_YOUR_API_KEY"
6)

JAVASCRIPT

1import OpenAI from "openai";
2 
3const client = new OpenAI({
4  baseURL: "https://api.modelriver.com/v1",
5  apiKey: "mr_live_YOUR_API_KEY",
6});

管理 API 密钥

创建密钥

打开 ModelRiver 控制台中的项目
进入 Settings → API Keys
点击 Create API Key
选择过期时间
复制并安全保存密钥，之后不会再次完整显示

吊销密钥

进入 Settings → API Keys
找到要吊销的密钥
点击 Revoke
该密钥会立即失效

警告： 吊销密钥会立即影响所有使用该密钥的应用。请先完成部署切换，再执行吊销。

密钥轮换

为了安全，建议定期轮换 API 密钥：

在控制台创建新密钥
更新所有部署以使用新密钥
验证所有服务都已切换成功
吊销旧密钥

环境变量方案

将密钥保存在环境变量中，而不要写入源码：

Bash

MODELRIVER_API_KEY=mr_live_YOUR_API_KEY

这样便于轮换、权限隔离以及按环境管理。

限流

API 密钥会根据你的套餐受到速率限制：

套餐	每分钟请求数	每月请求数
Free	60	25,000
Starter	120	100,000
Core	300	500,000
Growth	600	2,000,000

当达到限制时，会收到 429 响应。请参考错误处理实现重试与退避。

安全最佳实践

不要把密钥暴露在前端代码中：应始终通过后端代理调用 API
使用环境变量：将密钥保存在 .env 或密钥管理系统中
把 .env 加入 .gitignore：避免意外提交
按环境拆分密钥：生产、预发布、开发分别使用不同密钥
定期轮换密钥：至少每季度一次，或在泄漏后立即轮换
监控密钥使用情况：通过请求日志检查异常流量
开发环境使用短期密钥：让遗留密钥自动过期
限制网络访问：可行时使用 IP 白名单

后端代理模式

不要让浏览器直接调用 ModelRiver。正确做法是让前端请求你的后端，再由后端带着密钥请求 ModelRiver。

排查认证问题

错误	原因	解决方案
`401 authentication_error`	密钥无效或已过期	在控制台确认密钥状态，必要时创建新密钥
`401 missing_api_key`	缺少 `Authorization` 请求头	加入 `Bearer mr_live_...`
`403 forbidden`	密钥无访问权限	检查密钥所属项目是否正确
`429 rate_limit_exceeded`	请求过多	实现退避或升级套餐

下一步

迁移指南：从其他供应商迁移
安全：查看完整安全文档
错误处理：处理认证与权限相关错误

安全的 API 认证