🔑 ModelKey Pool

🚀 快速接入

将你日常使用的 AI 工具的 Base URL 设置为 https://你的域名/v1，API Key 随便填即可。

Cherry Studio / ChatBox / NextChat

API 地址:  https://你的域名/v1
API Key:   sk-no-needed（随便填）
模型名:    deepseek-ai/DeepSeek-V4-Pro

Cursor

Settings → Models → OpenAI API Key 里：

Base URL:  https://你的域名/v1
API Key:   sk-no-needed
Model:     deepseek-ai/DeepSeek-V4-Pro

Cline (VS Code 插件)

设置 → API Provider → OpenAI Compatible：

Base URL:  https://你的域名/v1
API Key:   sk-no-needed
Model ID:  deepseek-ai/DeepSeek-V4-Pro

OpenClaw

Settings → Model Providers → Add OpenAI Compatible：

Name:      ModelScope DeepSeek V4
Base URL:  https://你的域名/v1
API Key:   sk-no-needed
Model:     deepseek-ai/DeepSeek-V4-Pro

如果开启了外部 API Key 鉴权，把 sk-no-needed 换成你设置的 Key。

QwenPaw

在 .env 或环境变量中配置：

# 使用代理作为 OpenAI 兼容后端
OPENAI_BASE_URL=https://你的域名/v1
OPENAI_API_KEY=sk-no-needed
OPENAI_MODEL=deepseek-ai/DeepSeek-V4-Pro

如果是 QwenPaw Agent 配置，编辑 agents.yaml 或对应 agent 的 provider 配置：

provider: openai_compatible
provider_config:
  base_url: https://你的域名/v1
  api_key: sk-no-needed
  model: deepseek-ai/DeepSeek-V4-Pro

流式调用 (SSE)

所有接入方式都原生支持流式，只需在请求体加 "stream":true。代理会透传 SSE 事件流，延迟几乎为零。

# 流式 curl — 实时逐字输出
curl -N https://你的域名/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-ai/DeepSeek-V4-Pro","messages":[{"role":"user","content":"用 TypeScript 写一个快排"}],"stream":true}'

curl 命令行

# 非流式
curl https://你的域名/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-ai/DeepSeek-V4-Pro","messages":[{"role":"user","content":"你好"}]}'

# 流式 (SSE)
curl https://你的域名/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-ai/DeepSeek-V4-Pro","messages":[{"role":"user","content":"你好"}],"stream":true}'

Python (openai 库)

from openai import OpenAI

client = OpenAI(
    base_url="https://你的域名/v1",
    api_key="sk-no-needed"
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Pro",
    messages=[{"role":"user","content":"你好"}],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")

🔐 外部 API Key 鉴权

如果你把代理暴露在公网，建议设置一个对外 API Key 防止被刷：

1. 设置 Key

在 Vercel 项目 → Settings → Environment Variables 中添加：

API_KEY = sk-你自定义的密钥

重新部署后生效。

2. 客户端使用

所有工具的 Base URL 不变（/v1），只需把 API Key 从 sk-no-needed 换成你设置的密钥：

# curl 示例
curl https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk-你自定义的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-ai/DeepSeek-V4-Pro","messages":[{"role":"user","content":"你好"}]}'

3. 不设置

不设 API_KEY 环境变量时，代理不做鉴权，任何人可调用（适合内网或只有自己用的场景）。

⚙️ 工作原理

Key 选择策略

每次请求到来时，代理按以下逻辑选 Key：

• 🥇 跳过冷却中 — 刚被 429 限流的 Key 会冷却 5 分钟
• 🥈 跳过日配额耗尽 — 当天已调用 ≥200 次的 Key 不再使用
• 🥉 负载均衡 — 在剩余 Key 中选「剩余可用次数最多」的那把

故障切换

错误类型	处理方式
429 Too Many Requests	Key 冷却 5 分钟，自动切下一把
5xx 服务器错误	Key 冷却 1 分钟，自动重试
网络超时 / 断连	同上，自动重试
全部 Key 耗尽	返回 503，提示等待午夜重置

午夜自动重置

每次请求时检查日期。如果跨天，所有 Key 的日计数自动归零 + 解除冷却。无需手动操作。

📡 API 参考

POST /v1/chat/completions — 聊天代理（OpenAI 兼容）

完全兼容 OpenAI /v1/chat/completions 格式。也支持原始路径 /api/chat。支持 stream: true。

响应头 X-Key-Pool-Key 会显示本次使用了哪把 Key（脱敏）。

GET /api/keys — 获取 Key 池状态

curl https://你的域名/api/keys

返回所有 Key 的日用量、冷却状态、历史统计。

POST /api/keys — 添加 Key

curl -X POST https://你的域名/api/keys \
  -H "Content-Type: application/json" \
  -d '{"key":"ms-你的新Key"}'

DELETE /api/keys?key=xxx — 删除 Key

curl -X DELETE "https://你的域名/api/keys?key=ms-要删的Key"

POST /api/keys-test — 测试 Key

curl -X POST https://你的域名/api/keys-test \
  -H "Content-Type: application/json" \
  -d '{"key":"ms-要测的Key","model":"deepseek-ai/DeepSeek-V4-Pro","message":"Hello"}'

❓ 常见问题

Q: 日配额是多少？

ModelScope 每个 Key 每天 200 次调用。如果你有 5 个 Key，理论日总量是 1000 次。

Q: 配额什么时候重置？

每天午夜 00:00 自动重置。取决于 ModelScope 的时区（通常是 UTC+8）。

Q: 怎么知道哪个 Key 快用完了？

看管理面板的「Key 列表」— 进度条橙色（≥80%）或红色（耗尽）一目了然。

Q: 支持其他模型吗？

支持！ModelScope 上所有 OpenAI 兼容的模型都行。在 .env 里改 DEFAULT_MODEL 或请求时传 model 参数即可，比如 Qwen/Qwen3-235B-A22B。

Q: 数据存在哪？安全吗？

Key 存放在 Vercel 的环境变量 / KV 存储中，不会明文暴露给客户端。面板只显示脱敏 Key（如 ms-abc***xyz）。