Prometheus Lab · Developer Docs
接入 Prometheus API,
把模型能力带进你的工作流。
一个 Base URL,一把 API Key,一套 OpenAI 兼容接口。把社团统采的 DeepSeek、GLM、MiniMax、Kimi、MiMo 等模型接入终端、IDE、桌面客户端或你自己的脚本。
- Base URL
https://api.pmtlab.cn/v1- 鉴权
Authorization: Bearer <key>- 协议
- OpenAI Chat Completions
- 模型目录
GET /v1/models
GET /v1/models 只需鉴权、不消耗额度。用它确认 Key 是否有效,并拿到你有权限使用的准确模型名。
01 / QUICK START
首次调用 API
Prometheus API 使用 OpenAI 兼容的 Chat Completions 协议。拿到 Key 之后,只需要改三个参数:base_url、api_key 和 model。
| 参数 | 值 | 说明 |
|---|---|---|
base_url | https://api.pmtlab.cn/v1 | OpenAI SDK 的 base_url,或客户端的自定义 Base URL |
api_key | sicau-PMT-... | 在成员控制台创建;明文只在创建时显示一次 |
model | DeepSeek-V4.1-Flash 等 | 以 模型目录 或 /v1/models 为准 |
- 创建 API Key
登录成员控制台,在「API」页创建密钥。普通额度走
PLAN通道;管理员发放余额后才可以创建API通道密钥。 - 把 Base URL 填进客户端
任何支持自定义 OpenAI Base URL 的客户端都可以直接使用。常见工具的配置见接入 Agent 工具。
- 发送第一条请求
先用非流式请求确认 Key 和模型名可用,再打开流式输出,排查会简单得多。
curl https://api.pmtlab.cn/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PMT_API_KEY" \
-d '{
"model": "DeepSeek-V4.1-Flash",
"messages": [
{"role": "user", "content": "用 Python 写一个快速排序"}
],
"stream": false
}'
from openai import OpenAI
client = OpenAI(
base_url="https://api.pmtlab.cn/v1",
api_key="sicau-PMT-...",
)
resp = client.chat.completions.create(
model="DeepSeek-V4.1-Flash",
messages=[{"role": "user", "content": "用 Python 写一个快速排序"}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.pmtlab.cn/v1",
apiKey: process.env.PMT_API_KEY,
});
const resp = await client.chat.completions.create({
model: "DeepSeek-V4.1-Flash",
messages: [{ role: "user", content: "用 Python 写一个快速排序" }],
});
console.log(resp.choices[0].message.content);
想先确认 Key 是否有效,可以调用 GET /v1/models。它只需要鉴权,不消耗额度:
curl https://api.pmtlab.cn/v1/models \
-H "Authorization: Bearer $PMT_API_KEY"
不要把它写进前端代码、公开仓库或截图。发现泄露后请立刻在控制台删除并重建;密钥删除后无法恢复。
02 / MODELS
模型与价格
同一个模型背后可能由多个上游账号提供服务。网关会按账号池顺序选择渠道,对客户端始终暴露同一个模型名;上游临时切换时,客户端通常不需要改配置。
下面的目录和价格来自 GET /api/public/plans。价格单位为积分 / 百万 token(100 积分折算基准 1),实际按每次请求的 token 用量结算。
| 模型 | 上下文 | 输入 | 缓存读 | 输出 | 状态 |
|---|---|---|---|---|---|
| 正在读取模型目录… | |||||
03 / AGENT TOOLS
接入 Agent 工具
只要客户端支持「自定义 OpenAI 兼容提供商」或「自定义 Base URL」,就可以直接使用 Prometheus API。下面这些配置都使用同一个 Base URL,只有配置文件位置和字段名不同。
本站实现的是 OpenAI Chat Completions(/v1/chat/completions)和模型列表(/v1/models)。只支持 Anthropic Messages 或 OpenAI Responses 的工具需要桥接层,不能直接把 Base URL 填成本站地址。
Pi-Agent
把 Prometheus 添加成 Pi 的自定义 OpenAI Completions 提供商。
编辑 ~/.pi/agent/models.json,把 models 数组换成你要用的模型:
{
"providers": {
"prometheus": {
"baseUrl": "https://api.pmtlab.cn/v1",
"api": "openai-completions",
"apiKey": "$PMT_API_KEY",
"models": [
{ "id": "DeepSeek-V4.1-Flash" },
{ "id": "GLM-5.3-Flash" }
]
}
}
}
设置 PMT_API_KEY 后重启 Pi,在模型切换器中选择 Prometheus 提供商。
OpenCode
通过 AI SDK 的 OpenAI 兼容 provider 接入。
在项目根目录的 opencode.json 中加入:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"prometheus": {
"npm": "@ai-sdk/openai-compatible",
"name": "Prometheus API",
"options": {
"baseURL": "https://api.pmtlab.cn/v1",
"apiKey": "{env:PMT_API_KEY}"
},
"models": {
"DeepSeek-V4.1-Flash": { "name": "DeepSeek V4.1 Flash" },
"GLM-5.3-Flash": { "name": "GLM 5.3 Flash" }
}
}
}
}
models 的键必须与 /v1/models 返回的 id 一致。桌面版可在设置中直接填 Base URL 与 Key。
Hermes
用 Custom Endpoint 指向 Prometheus API。
推荐运行 hermes model,选择 Custom endpoint,依次填写 Base URL、API Key 和模型名。也可以直接编辑 ~/.hermes/config.yaml:
model:
default: DeepSeek-V4.1-Flash
provider: custom
base_url: https://api.pmtlab.cn/v1
api_key: sicau-PMT-...
Hermes 的视觉、压缩等辅助任务默认复用主模型;需要时可以分别指定更轻量的模型。
WorkBuddy / CodeBuddy
通过本地 models.json 添加 OpenAI 兼容模型。
创建或编辑 ~/.codebuddy/models.json(Windows 为 C:\Users\<你的用户名>\.codebuddy\models.json):
{
"models": [
{
"id": "DeepSeek-V4.1-Flash",
"name": "DeepSeek V4.1 Flash",
"vendor": "Prometheus",
"url": "https://api.pmtlab.cn/v1/chat/completions",
"apiKey": "${PMT_API_KEY}",
"maxInputTokens": 1000000,
"maxOutputTokens": 128000,
"supportsToolCall": true,
"supportsImages": false
}
],
"availableModels": ["DeepSeek-V4.1-Flash"]
}
保存为 UTF-8 无 BOM,然后完全退出并重启 WorkBuddy / CodeBuddy。
OpenAI SDK
任何语言都可以直接使用官方 SDK 或自己发 HTTP 请求。
Python 示例:
from openai import OpenAI
client = OpenAI(
base_url="https://api.pmtlab.cn/v1",
api_key="sicau-PMT-...",
)
resp = client.chat.completions.create(
model="DeepSeek-V4.1-Flash",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
流式、工具调用与思考档位都可以按 OpenAI Chat Completions 的方式使用,详见流式、思考与工具。
协议兼容性
| 客户端类型 | 接入方式 | 说明 |
|---|---|---|
| Pi / OpenCode / Hermes | 直接接入 | 支持自定义 OpenAI 兼容 Base URL,使用上面的配置。 |
| WorkBuddy / CodeBuddy | 直接接入 | 通过本地 models.json 添加自定义模型。 |
| Cherry Studio / Cline / LobeHub 等 | 直接接入 | 在「OpenAI 兼容」提供商里填 Base URL 和 Key;以客户端是否提供自定义地址为准。 |
| Claude Code | 需要桥接 | 原生使用 Anthropic Messages 协议,需经 OpenAI 兼容桥接。 |
| OpenAI Codex | 需要桥接 | 原生使用 Responses API,需通过 Moon Bridge 等转发层转换。 |
更多客户端指南
awesome-deepseek-agent 收录了 20 多个 Agent 与编程助手的接入教程。下面这些工具支持自定义 OpenAI 兼容地址,接入本站时只需把示例里的 Base URL 与 Key 换成自己的:
04 / FREE CHANNELS
免费渠道与限免
文档里会出现两种「免费」,它们的入口和计费含义不同。模型表上的状态标记会实时反映当前情况。
-free 变体
同一个模型走社团接入的福利账号渠道。调用时在模型名后加 -free,例如 Step-5-Preview-free。
- 计 0 积分,不占日、周或单模型额度。
- 仍受模型白名单和 Key 的 token 上限约束。
- 只有当前有福利账号在提供时才会出现在
/v1/models;没有渠道时返回503 free_unavailable。 - 福利上游是共享额度,额度窗口通常在北京时间 22:00 恢复;429 响应会尽量给出
Retry-After。
上游阶段免单
某些模型在上游另有一张免费 key。此时模型名不加后缀,照常调用,网关实际走免费 key。
- 上游不收费,所以网关也记 0 积分,并跳过额度门。
- 与
-free不是一回事:不需要加后缀,也不走福利账号池。 - 上游随时可能收回免费 key;收回后会立刻恢复按正价计费与额度限制,不需要你改配置。
- 是否限免以模型表或 Plan 页的实时标记为准。
免费渠道由第三方或共享账号提供,可用时间和稳定性都不保证。重要任务请使用正常计费模型,或为客户端配置失败重试。
05 / USAGE & BILLING
额度与计费
平台有两条独立通道,互不影响:PLAN 按档位积分额度扣减,API 按管理员发放的积分余额扣减。所有消费与额度统一按积分计算。
PLAN 通道
额度按成本而不是请求次数计算。每次请求的输入、缓存读取、缓存写入和输出分别按单价折算,再累加到额度里。
额度不是简单的「总金额 ÷ 单价」,而是按模型份额累加:每个模型都有自己的日额度与周额度,一次调用占用「本次花费 ÷ 该模型额度」的百分比,各模型百分比之和达到 100% 时通道停止。一个模型自己先到 100% 时,只停这一个模型。
| 档位 | 日预算 | 周预算 | 说明 |
|---|---|---|---|
| 正在读取档位数据… | |||
档位余额是额度池的基准;具体到每个模型的分摊额度会按档位比例缩放。完整的逐模型额度见 Plan 页,管理员也可以为单个成员或单个模型单独覆盖。
- 日额度:服务器本地时间每天 0 点重置。
- 周额度:每周一 0 点重置,按本周一以来的消耗计算。
- 限额为 0:表示不限额,按不限处理;已下架模型的历史用量不重新推进额度池。
- 手工覆盖:管理员可以为成员设置总预算或单个模型的额度;修改只影响之后的使用,不追溯已经发生的账目。
API 通道
API 通道没有日限和周限,只受余额约束。余额由管理员发放,调用时按实际成本扣减;余额耗尽后返回 429 api_balance_exhausted。余额变动写入可审计的账本,充值 / 冲正都以追加记录完成。
额度用满时
返回 429 与具体错误码:quota_daily_exceeded、quota_total_exceeded 或 model_quota_exceeded。带 Retry-After 时按它等待;没有时可按日 / 周重置时间或模型页提示处理。
登录 成员控制台 → 模型 可以看到每个模型的单价、当前额度与已用百分比。
06 / STREAMING
流式、思考与工具调用
把请求里的 stream 设为 true 即走 Server-Sent Events。网关会把上游的 SSE 帧统一整理成 OpenAI 兼容格式,正常结束时以一行 data: [DONE] 收尾。
curl -N https://api.pmtlab.cn/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PMT_API_KEY" \
-d '{
"model": "DeepSeek-V4.1-Flash",
"messages": [{"role": "user", "content": "写一个二分查找"}],
"stream": true
}'
stream = client.chat.completions.create(
model="DeepSeek-V4.1-Flash",
messages=[{"role": "user", "content": "写一个二分查找"}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")
思考档位
用 reasoning_effort 控制思考深度。网关保留上游支持的档位:none、minimal、low、medium、high、max、xhigh;无法识别的值会被丢弃,而不是让整条请求失败。不同模型实际支持的范围可能不同,以模型表现为准。
工具调用
OpenAI 风格的 tools 与 tool_calls 会随请求透传;tool_choice 支持字符串形式,传对象时网关会折算成等价的函数名。工具参数本身不会被平台保存。
流式响应一旦开始,HTTP 状态码就已经固定。若上游在中途断开,客户端可能先收到部分内容后连接结束;如果结束时没有 [DONE],请把这一轮视为失败并按需重试。非流式请求则会直接返回错误 JSON。
07 / API REFERENCE
API 参考
所有 /v1 接口使用 Bearer Token 鉴权。成功时返回 OpenAI 兼容 JSON;失败时返回统一错误信封。
/v1/models列出当前 Key 可用的模型返回的 id 可以直接作为请求里的 model。没有权限的模型不会出现;福利渠道没有账号提供时,对应的 -free 变体也不会出现。
{
"object": "list",
"data": [
{
"id": "DeepSeek-V4.1-Flash",
"object": "model",
"name": "DeepSeek-V4.1-Flash",
"context": 1000000,
"max_output": 128000,
"owned_by": "oh-pmt-api"
}
]
}
/v1/chat/completions创建一次对话补全请求体按 OpenAI Chat Completions 规范发送。网关会把上游请求整理为流式,再根据你请求里的 stream 字段决定返回 SSE 还是聚合后的完整 JSON。
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
model | string | 是 | 模型名,使用 /v1/models 返回的 id |
messages | array | 是 | OpenAI 格式的消息数组;developer 会等价为 system |
stream | boolean | 否 | 是否使用 SSE;默认 false |
tools | array | 否 | 工具定义,随请求发送给上游 |
tool_choice | string / object | 否 | 字符串原样发送;对象形式会折算为等价的函数名 |
reasoning_effort | string | 否 | 思考强度,取值见上一节 |
其余 OpenAI 字段按需传递即可。不要发送客户端用不到或上游不认识的字段,避免被上游判定为非法请求(upstream_rejected)。
/health服务存活检查不需要鉴权。返回 {"status":"ok","node":"sg-1","time":...},适合给负载均衡器或监控探活使用。它不是模型可用性检查;模型能不能用请调用 /v1/models。
请求头
| Header | 值 | 说明 |
|---|---|---|
Authorization | Bearer sicau-PMT-... | 推荐方式 |
X-API-Key | sicau-PMT-... | 部分 SDK / 客户端不支持 Bearer 时的替代写法 |
Content-Type | application/json | POST 请求必需 |
错误响应格式
所有错误都使用同一层信封,HTTP 状态码与 error.code 同时表达原因:
{
"error": {
"code": "model_quota_exceeded",
"message": "模型 DeepSeek-V4.1-Flash 的今日额度已用完(100.0%),23:59 重置",
"type": "model_quota_exceeded"
}
}
完整错误码见错误码。
08 / ACCOUNT
账号与密钥
成员账号
账号由管理员创建。初始密码会私下告知,首次登录后请在成员控制台修改密码。管理员无法查看你改后的密码,只能重置成初始密码。
API Key
密钥由成员自己在控制台创建和删除。明文只在创建成功的那一刻显示一次,之后数据库只保存 SHA-256 哈希,任何人都无法取回原文。丢失后请删除并新建。
每人最多保留 20 把密钥。管理员只能看到前缀和启停状态,不能读取或重置成员密钥。
按档位额度
默认通道。请求成本累计到成员的档位额度,日、周窗口独立重置。适合日常使用。
按余额扣减
管理员发放余额后可用。没有日限和周限,余额耗尽即停止;余额为 0 时不能创建 API 通道密钥。
不要分享给同学,也不要写进公开仓库。如果你怀疑 Key 泄露,请直接删除并重建。
控制台登录连续失败会触发 429 login_locked,稍后再试即可;接口调用不会因为登录失败被锁定。
09 / ERRORS
错误码
优先按 HTTP 状态码判断大类,再按 error.code 做具体处理。429 请读取 Retry-After,不要立即重试。
| HTTP | code | 含义与处理 |
|---|---|---|
| 401 | missing_api_key | 请求没带 Key。补上 Authorization 或 X-API-Key。 |
| 401 | invalid_api_key | Key 不存在或已停用。检查 Key 是否复制完整,或重新创建。 |
| 403 | ip_forbidden | 来源 IP 不在 Key 的白名单里。联系管理员,不要反复重试。 |
| 403 | model_forbidden | 这个模型没有开给你的 Key / 成员。到 /v1/models 查看自己的可用列表。 |
| 404 | model_not_found | 模型名不存在。使用目录返回的 id。 |
| 410 | model_retired | 模型已下架。改用新版本,或从 /v1/models 重新选择。 |
| 429 | model_quota_exceeded | 这个模型自己的日 / 周额度已用满;其他模型可能仍然可用。 |
| 429 | quota_daily_exceeded | PLAN 通道今日额度已用满,等待每日 0 点重置。 |
| 429 | quota_total_exceeded | PLAN 通道本周额度已用满,等待下周一 0 点重置。 |
| 429 | api_balance_exhausted | API 通道余额不足,需要管理员发放。 |
| 429 | token_limit_exceeded | 这把 Key 的 token 用量达到管理员设置的上限。 |
| 429 | free_rate_limited | 免费渠道的共享额度被限流。按 Retry-After 等待,通常在北京时间 22:00 恢复。 |
| 429 | upstream_busy | 上游模型繁忙。按 Retry-After 退避后重试。 |
| 429 | upstream_limited | 上游账号临时受限,网关已切换 / 冷却账号。稍后再试。 |
| 400 | upstream_rejected | 请求内容被上游渠道校验拒绝。调整消息 / 工具定义后再试。 |
| 502 | upstream_auth | 上游鉴权失败,属于平台侧问题。稍后重试并关注状态。 |
| 502 | upstream_error | 上游响应中断或返回未知错误。可做有限次退避重试。 |
| 503 | free_unavailable | 当前没有福利账号提供这个 -free 模型。去掉后缀使用正常模型,或稍后再试。 |
| 503 | no_account | 账号池暂时没有可用账号。稍后重试。 |
| 503 | database_unavailable | 平台数据库暂时不可用。不要把它当作 Key 失效。 |
| 500 | internal_error | 平台内部错误。记录时间与状态码后反馈给管理员。 |
重试建议
401/403/404/410:不要自动重试,修正 Key、权限或模型名。429:读取Retry-After,按等待时间退避;没有该头时使用指数退避。502/503:可以有限次重试(例如最多 3 次),并在每次之间增加间隔。流式请求重试前请确认上一轮没有收到[DONE]。
10 / PRIVACY
隐私与数据
平台只保存计费、排障和聚合统计需要的元数据,不保存请求与响应的正文。
会保存
- 模型名、输入 / 输出 / 缓存 token 数、折算成本
- HTTP 状态码、错误码、来源 IP、时间戳
- 所属成员、所使用的平台账号与出口标识
不会保存
- 消息正文、系统提示词、工具调用参数
- 模型输出、文件内容与代码片段
- 任何用于训练或对外出售的数据
请求内容会转发给实际提供模型的上游服务,并受对应上游条款约束。公开的 Data 看板只展示聚合后的 token、成本与留存指标;成员以序号出现,不显示姓名、邮箱或密钥。
如果你对数据留存有特殊要求,或需要确认某个模型的隐私边界,请先联系社团管理员再使用。
11 / FAQ
常见问题
模型名大小写敏感吗?
不敏感。网关会忽略大小写、空格、连字符和点,所以 deepseek-v4.1-flash 与 DeepSeek-V4.1-Flash 指向同一个模型。不过建议直接使用 /v1/models 返回的写法,避免客户端展示和日志对不上。
为什么请求返回 429?
先看 error.code。quota_daily_exceeded / quota_total_exceeded 是通道额度用满,等日或周窗口重置;model_quota_exceeded 只是这个模型满了,可以换模型;upstream_busy 是上游忙,按 Retry-After 等待;api_balance_exhausted 则需要管理员发放余额。
带 -free 的模型为什么突然不见了?
免费变体只有在当前有福利账号提供该模型时才会出现在 /v1/models。账号被停用、模型测活失败或共享额度用尽时,列表会实时收缩。此时去掉 -free 使用正常模型,或稍后刷新目录。
Claude Code / Codex 能直接填 Base URL 吗?
不能直接填。Claude Code 原生使用 Anthropic Messages API,Codex 原生使用 OpenAI Responses API,而本站当前提供的是 OpenAI Chat Completions。需要在中间运行协议桥接(例如 Codex 可用 Moon Bridge),再把桥接服务指向 Prometheus API。
调用并发有限制吗?
平台不按并发数额外限流,额度按成本累计。但上游账号池的并发能力有限,请求太集中时可能表现为延迟升高或偶发 upstream_busy,因此建议客户端使用有限并发并做好退避。
可以把 Key 分享给同学吗?
不建议,也可能违反社团使用约定。额度按 Key 记录,分享出去等于把配额、IP 限制和风控风险一起交给别人;出问题时也难以区分是谁的流量。每人应使用自己的 Key。
API Key 丢了还能找回来吗?
不能。数据库只保存哈希,明文只在创建成功时出现一次。请删除旧 Key 并重新创建;如果旧 Key 可能泄露,删除本身就是必要的止损动作。