灵策中台接入指南：用应用 Key 调模型

后台登记的「中台应用」可以用自己的 API Key 调灵策的模型网关，接口是 OpenAI 兼容的 /api/v1/*，费用从应用绑定组织的积分钱包里扣，限额和频率按这把 Key 单独设。登录见 统一登录，收款见 收款与 Webhook，通知与文件见 通知与文件。

#1. 怎么拿到 Key

由灵策运营（超级管理员）在后台「灵策中台 → 应用 → 开通模型调用」里开通：

1. 选付费组织：
   • 默认新建一个专属企业组织「中台应用 · <应用名>」（自带零余额钱包），应用的消耗单独记账；
   • 也可以绑定一个已有的企业组织（比如应用就是某个企业客户自己的产品），直接花它的积分。个人组织不能绑；
   • 吊销后重新开通默认沿用上次的组织，余额不丢。
2. 设能力和策略（之后可随时改，立即生效）：能力（对话 / 出图 / 出视频）、允许的模型、每分钟请求数、每分钟 token 数、每日 / 每月积分上限。
3. 点「开通」后弹出 sk-… 明文 Key 和 baseURL，只显示这一次。灵策只存哈希，丢了只能轮换。

Key 只能放在你的服务端（环境变量 / 密钥管理），不要放进前端、App 安装包或小程序。

#2. 调用

baseURL：https://center.lynxce.cn/api/v1（和 https://api.lynxce.cn/api/v1 是同一组服务，用哪个都行）。 @ai-employee/center-sdk 里不需要专门的模型客户端，直接用 OpenAI 官方 SDK：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://center.lynxce.cn/api/v1",
  apiKey: process.env.LYNXCE_MODEL_API_KEY, // 后台开通时拿到的 sk-…
});

const completion = await client.chat.completions.create({
  model: "deepseek-chat", // 以 GET /api/v1/models 返回的 id 为准
  messages: [{ role: "user", content: "用一句话介绍灵策智算" }],
});
console.log(completion.choices[0].message.content);

• GET /api/v1/models 列出这把 Key 当前能用的模型（已按组织权限过滤；后台设了「允许的模型」时只能调列表里的）。auto 或不传 model 由平台选模型，选中的模型不在名单内时返回 403 api_key_model_forbidden，名单里写 auto 不算放开；
• POST /api/v1/chat/completions、POST /api/v1/responses 对话，支持 stream: true；
• 非流式请求可以带 Idempotency-Key 请求头，同键重放 24 小时内返回同一结果、不重复扣费（流式不支持，带了会 400）；
• 开了出图 / 出视频能力时可用 /api/v1/images/generations、/api/v1/videos/generations（异步任务，GET /api/v1/generations/:id 查结果）。

失败切换：对话请求的模型在开始返回内容之前失败（限流、配额耗尽、超时、上游 5xx），网关会自动切到同能力的其他模型：

• 切换只发生在首个有效内容之前；流式内容开始后上游再出错不会换模型，这个请求按失败处理；
• 设了「允许的模型」时只切到名单内的模型，名单外的一律跳过。想要切换空间就多填几个；只填一个模型等于不切换，主模型的错误原样返回；
• 名单填 /api/v1/models 的模型 id 时，同一模型换线路算允许；填 供应商::模型 只放行这一条线路；
• 切换后响应的 model（流式为每一帧及 /responses 的事件）是实际跑的模型，响应头 X-Model-Switched 写明 from=…;to=…;reason=…；
• 按实际模型计费，一个请求只结算一次，同一个 Idempotency-Key 重放也不会再切换或再扣费；
• 候选比主模型贵时，日 / 月积分上限按候选的预估重新占用，容不下就跳过这个候选；
• 客户端断开后不再发下一个候选。

#3. 计费

• 和企业集成密钥同一条计费链路：调上游之前先检查钱包余额（失败切换时每个候选都查），结算在数据库事务里按幂等键扣一次，不会重复扣；
• 价格就是模型目录里的积分价（含组织倍率），单位是灵策积分（1 元 = 100 积分）；
• 部分模型只对有有效会员套餐的企业开放（403 premium_text_model_required）；专属组织默认没有套餐，需要的话让运营在组织详情里开通；
• 充值：没有单独的充值接口。运营在后台「灵策中台 → 应用 → 模型调用」弹窗里点「充值（人工调账）」，走现有的人工调账（钱包 + 账本 + 高风险审计）；绑定的是企业客户组织时，客户也可以用自己的企业充值渠道。弹窗里能看到余额和今日 / 本月消耗。

#4. 限额

注意：限额按 Key 计，轮换后新 Key 的日 / 月计数从 0 开始，旧 Key 在 24 小时宽限期内也有自己的一份 RPM。

TPM 是事后计数：token 数只有响应结束才知道，所以每个请求结算后（流式在流结束时）才把实际用量记进窗口，新请求进来时看窗口是否已到上限。这意味着：

• 单个请求可以冲过上限，并发请求也可以同时放行，这是设计如此，不是 bug。超出的部分会让后面的请求多等一会；要卡死成本请用积分上限；
• 只有按 token 计费的接口受影响：/v1/chat/completions、/v1/responses、/v1/embeddings。查模型、出图、出视频、查任务不计入也不被拦；
• 上游没返回 usage 的流式请求按 0 token 计；被 429 拦下的请求不占 RPM、不扣费；幂等重放不计入也不被拦；
• Redis 故障时和 RPM 一样退回数据库：改按账本统计近 60 秒用量，限制继续生效，此时 Retry-After 固定 60 秒。

#5. 错误码

错误体是 { "error": { "code": "...", "message": "..." } }：

#6. 轮换与吊销

• 轮换：后台「轮换 API Key」生成新 Key（沿用能力与策略），默认旧 Key 再用 24 小时，期间两把都能调用；怀疑泄露时勾选「立即吊销旧 Key」。宽限期内再轮换一次，最早那把立即失效。
• 吊销：全部 Key 立即失效、不可恢复；组织和余额保留，可以重新开通（会发新 Key）。
• 停用中台应用时模型 Key 同时暂停，重新启用后恢复；要永久作废请吊销。

#已知限制

• center.lynxce.cn 只开放 /api/v1/*，应用不用接 /api/proxy/v1/*。两条路径都有失败切换，「允许的模型」对切换候选同样生效；IP 白名单、RPM、TPM 也一样，换 baseURL 绕不过去。Redis 不可用时 /api/proxy/v1/* 的 RPM 暂不生效，那边也没有 Idempotency-Key 和请求记录。
• TPM 不是硬上限：没有「预估占用」，判定时看不到进行中的请求（见第 4 节）。严格的成本上限靠每日 / 每月积分上限。
• 用量按 Key 统计，没有按「应用的终端用户」拆分；需要的话在应用侧自己记。
• 绑定的若是企业客户组织，这把 Key 也会出现在该企业网页版的「API 密钥」列表里，企业管理员可以暂停或删除它。