文档账户与额度
文档目录

开放 API Key

给外部程序调用 Proma Open API 的密钥:可设初始额度、随时启停、按积分限额;第三方应用与 Agent 工具按协议接入的方式也在这页。

更新于 2026年11月11日

开放 API 供外部脚本或应用直接调用 Proma 的模型服务,消耗同一个账户余额。这一页管理密钥本身:建几个、各自能花多少、什么时候停用。

只在登录状态出现,左导航位置在「购买额度」之后。

密钥列表

「API Keys」下方写着「您创建的所有 API Keys」,右上「创建 API Key」。表格列是名称、Key、状态、请求、消耗、限额和最后使用时间,行末是操作按钮。

  • Key 列只显示前三段形式:前 7 位、省略号、后 4 位,旁边有复制按钮,复制成功短暂变成对勾。
  • 状态三种:绿点「启用」、「禁用」、「已过期」。
  • 消耗显示已用积分。
  • 限额显示「不限制」「剩余 N 积分」或「已用完」。
  • 行末三个操作:编辑、启用/禁用开关、删除。

空态是「还没有 API Keys」,并提示「点击上方按钮创建您的第一个 API Key」。

创建

对话框三个字段:

  • 名称:必填,最长 100 字,占位「例如:生产环境、测试环境」。
  • 描述:可选,占位「用于描述此 API Key 的用途」。
  • 用量限额:「不限制」或「设置初始额度」,后者填积分数,未填或不大于 0 时提示「请输入有效的初始额度」并不提交。

创建成功后对话框标题变成「API Key 已创建」,Key 默认打码,可以点眼睛图标显示,也可以复制。同时有一条警告:「请务必妥善保管好你的 API KEY,通过此 API KEY 会直接消费你的 Proma 余额。」

关掉对话框后表单和刚创建的 Key 一起清空,列表立即刷新。

编辑

编辑对话框可以改名称、描述和限额。已经有额度的 Key 会显示「当前剩余」,额度调整框接受正负值——正数增加、负数减少——并实时显示「调整后剩余」。

启用开关是即时生效的,切换失败不会额外提示。

删除

删除前确认「确认删除」,正文是「此操作不可撤销,所有使用此 Key 的应用将无法访问 API。」

使用说明

「API 使用说明」卡可以展开,给出 Open AI Chat Completions、OpenAI Responses、Anthropic Messages 和 /v1/models 的调用示例,基础地址是 https://api.proma.cool/v1。

其中三点需要先了解:

  • 只支持 Responses 接口的模型,请求体用 input 而不是 messages;具体哪些模型如此,以 /v1/models 的返回和页面上的调用示例为准。
  • Anthropic 协议的鉴权头是 X-Api-Key。
  • 模型清单可以直接查 /v1/models,不用写死在代码里。

第三方应用接入

凡是允许填自定义基础地址、并支持 OpenAI 或 Anthropic 协议的应用,都能用这把 Key 调同一套模型服务,不需要在 Proma 里逐个登记。基础地址是 https://api.proma.cool/v1;只认自家账号登录、不给改地址的应用接不进来。

常见客户端按它支持的协议分四类:

  • OpenAI Chat Completions(/v1/chat/completions):图形界面的聊天客户端和多数 IDE 插件走这一路,例如 Cherry Studio、Chatbox、LobeChat、Cline;它们的「自定义供应商」入口通常只要基础地址和 Key。
  • OpenAI Responses(/v1/responses):只认 Responses 的编码 Agent 走这一路,请求体用 input 而不是 messages。
  • Anthropic Messages(/v1/messages):Claude Code、Anthropic SDK 和声明支持 Anthropic 协议的应用,鉴权头是 X-Api-Key;这类应用的基础地址一般填到域名层 https://api.proma.cool,由 SDK 自己拼出 /v1/messages。
  • Gemini 原生格式(/v1beta):只对声明支持该协议的模型开放,用前先查模型清单。

Agent 框架和编码工具也一样,只是要填的项目更多。以 DeepSeek Harness 为例,它的「设置 → 模型 → 添加自定义提供方」要求提供方 ID、基础地址、协议、Key 和至少一个模型;协议必须选地址实际提供的那一种,同一地址提供多种协议时按协议分别建提供方。它自带的「获取可用模型」读的是 /v1/models,端点不答或返回空时手填模型 ID,效果一样。具体入口名称随应用版本变化,以应用内为准。

模型与协议的对应关系可以直接从 /v1/models 读,这个接口不用密钥:每个模型带 supported_apis,列出它能接受的协议,模型 ID 也以这里为准。选错协议、填错模型 ID 或该模型没有开放,都会在请求时失败。能列出模型只说明它可被请求,不说明它支持工具调用或图片输入,这些要看模型本身的能力。

注意

  • 密钥即余额:持有者可以直接消耗账户额度,不要写进前端代码、公开仓库或截图。
  • 限额是硬上限,用完就返回失败,不会自动续;需要继续用就去编辑里调整。
  • 删除是不可恢复的,正在用它的应用会立刻全部失效,换 Key 要同步改配置。
  • 密钥没有绑定应用或设备的概念,只有名称和描述用于区分用途;谁在用只能靠最后使用时间和消耗量来判断。
  • 列表里的 Key 是打码显示,完整值以创建那次为准,建议创建时立即存入密码管理器。
  • 在第三方应用里填过的 Key 由那个应用自己保存,谁能看到取决于应用;在他人设备或临时环境试用完,回来把对应的 Key 禁用。
  • Agent 类应用每一轮都会把文件内容和工具输出重新送回模型,积分消耗比聊天快得多,给这类用途单独建一把 Key 并设限额更稳妥。
本页内容