API 密钥管理
子账户密钥按部门/业务线/成本中心分账的设计意图，密钥的申请、变更、注销流程，安全最佳实践，单方暂停与恢复，到期与轮换
平台以子账户密钥为接入与分账的基本单元。您可以为不同的部门、业务线或成本中心分别申请独立的 API 密钥，所有查询用量按所用密钥自动归属、独立计量，便于在用量明细与结算单中逐项核对。
本文介绍子账户密钥的分账设计意图、申请与变更流程、安全使用建议，以及单方暂停、到期与轮换等运维操作。密钥本身用于数据平面的查询调用鉴权；申请、变更、查询等管理操作通过控制台的 接入管理 · API 密钥 页面完成。
为什么按子账户分账
平台不要求您把所有应用挤在一把密钥下，而是鼓励一类用途一把密钥。每把密钥可标注其所属维度，平台按密钥维度归集用量：
| 分账维度 | 典型用法 | 在用量与账单中的体现 |
|---|---|---|
| 部门 | 研发、客服、风控等各部门各持一把 | 用量明细按密钥分项小计，账单按密钥分项列示 |
| 业务线 | 智能问答、文档处理、质检助手等各业务线独立计量 | 可单独查看某业务线的统一计价词元消耗与金额 |
| 成本中心 | 按内部核算单元拆分，便于成本归集与内部结算 | 月度结算单按密钥分项，便于内部分摊 |
分账即计量切片。 单把密钥的用量，就是用量明细按该密钥维度的切片；按密钥分项之和等于账户合计。您在密钥页看到的单密钥用量，与用量明细、结算单中的对应分项完全同源，逐项对得上。不同业务的用量互不混淆、成本可独立归集；某把密钥若泄露或不再使用，可单独处置而不影响其他业务。
密钥列表与状态
控制台的 API 密钥 页以列表形式呈现账户下的全部子账户密钥，每行包含名称、所属维度、状态、已用与额度进度、可调用模型范围、到期时间与最后使用时间。
| 列 | 含义 |
|---|---|
| 名称 | 密钥的备注名，建议体现用途（如 研发-智能问答） |
| 部门 / 业务线 | 该密钥的分账维度标注 |
| 状态 | 正常 / 已暂停 / 已注销 / 已到期 |
| 已用 · 额度进度 | 该密钥已消耗的统一计价词元用量（额度为账户单层汇总，见下文） |
| 模型范围 | 该密钥被授权调用的模型清单 |
| 到期 | 密钥的到期时间（可设为不过期） |
| 最后使用 | 最近一次成功调用的时间 |
对应的查询接口（控制平面，需控制台会话）：
curl https://<平台入口地址>/api/v1/keys?page=1&page_size=20&status=active \
-H "Authorization: Bearer <控制台会话凭证>"{
"total": 0,
"page": 1,
"page_size": 20,
"items": [
{
"api_key_id": "<子账户标识>",
"name": "研发-智能问答",
"dimension": "业务线",
"status": "active",
"used_tokens": 0,
"model_scope": ["<模型名>"],
"expires_at": "2026-12-31",
"last_used_at": "2026-06-07 10:21:38"
}
]
}列表支持按状态与分账维度筛选、按时间排序。响应统一含
items数组与total总条数，分页参数page/page_size。
申请新密钥
为一个新部门或业务线开通接入时，申请一把新密钥：
curl -X POST https://<平台入口地址>/api/v1/keys \
-H "Authorization: Bearer <控制台会话凭证>" \
-H "Content-Type: application/json" \
-d '{
"name": "客服-工单摘要",
"dimension": "业务线",
"model_scope": ["<模型名>"],
"expires_at": "2026-12-31"
}'响应返回新密钥的摘要信息。密钥本体（tsxt- 前缀的完整字符串）仅在创建时返回一次，请立即妥善保存：
{
"api_key_id": "<子账户标识>",
"name": "客服-工单摘要",
"api_key": "tsxt-xxxxxxxxxxxxxxxxxxxxxxxx",
"dimension": "业务线",
"model_scope": ["<模型名>"],
"expires_at": "2026-12-31",
"status": "active"
}密钥只展示一次。 出于安全考虑，密钥明文仅在创建响应中返回一次，平台不再二次明示。若遗失，请按下文轮换流程注销旧密钥并重新申请，而非尝试找回。
变更密钥
密钥创建后，名称、分账维度、可调用模型范围、到期时间均可调整（密钥本体不变）：
curl -X PUT https://<平台入口地址>/api/v1/keys/<子账户标识> \
-H "Authorization: Bearer <控制台会话凭证>" \
-H "Content-Type: application/json" \
-d '{
"name": "客服-工单摘要(华东)",
"model_scope": ["<模型名>"],
"expires_at": "2027-06-30"
}'变更立即生效，返回更新后的密钥摘要。变更密钥的可调用模型范围，会影响该密钥后续可发起的查询；缩小范围不影响历史用量记录。
单方暂停与恢复
当某把密钥需要临时停用（如怀疑泄露、业务暂停、安全排查）时，可对单把密钥执行暂停，而不影响其他密钥的正常使用：
curl -X POST https://<平台入口地址>/api/v1/keys/<子账户标识>/suspend \
-H "Authorization: Bearer <控制台会话凭证>"暂停后该密钥发起的查询将被拒绝，状态变为「已暂停」。排查完成后可随时恢复：
curl -X POST https://<平台入口地址>/api/v1/keys/<子账户标识>/resume \
-H "Authorization: Bearer <控制台会话凭证>"区分两种暂停。 上述为您对单把密钥的主动暂停。另有一种由账户信用额度触发的暂停：当账户当月用量触及汇总信用额度上限时，账户下全部密钥会一并暂停，直至额度恢复或完成提额。信用额度为账户单层汇总、约束全部密钥，没有按单把密钥设置的子额度——单把密钥的「已用·额度进度」仅作用量提示，不构成独立限额。额度机制详见额度管理。
注销密钥
某把密钥不再需要时，将其注销：
curl -X DELETE https://<平台入口地址>/api/v1/keys/<子账户标识> \
-H "Authorization: Bearer <控制台会话凭证>"注销为软注销：密钥状态变为「已注销」并立即停止鉴权，但其历史用量记录与所属分项仍保留在用量明细与结算单中，以便对账。
可复用的与不可复用的。 注销后，该密钥承载的业务线名 / 备注名可在新密钥上复用；但密钥本体（
tsxt-字符串）不可复用——重新申请会得到一把全新的密钥。
到期与轮换
为降低长期有效密钥的泄露风险，建议为密钥设置合理的到期时间，并定期轮换：
| 操作 | 做法 |
|---|---|
| 设置到期 | 申请或变更时设置 expires_at；到期后密钥自动失效，状态转为「已到期」 |
| 提前续期 | 在到期前通过变更接口延后 expires_at |
| 计划轮换 | 申请一把新密钥 → 将业务流量切换到新密钥 → 确认无残留调用后注销旧密钥 |
| 紧急轮换 | 怀疑泄露时，先暂停旧密钥止血，再申请新密钥切换，最后注销旧密钥 |
轮换时建议采用「先建后撤」的顺序，避免业务中断：新旧密钥可短暂并存，待新密钥承接全部流量后再注销旧密钥。
单密钥用量查询
需要单独核对某把密钥的消耗时，可直接查询该密钥的分账用量（即用量明细按该密钥维度的切片）：
curl "https://<平台入口地址>/api/v1/keys/<子账户标识>/usage?start=2026-06-01&end=2026-06-30" \
-H "Authorization: Bearer <控制台会话凭证>"返回该密钥在指定时间范围内的统一计价词元用量（按 6 档计量口径）与对应金额，与用量明细、账单与结算中的对应分项完全同源。具体单价与额度等商务数值不在本文档中固化，以服务协议与控制台实时口径为准。
安全最佳实践
密钥是访问平台的凭证，等同于您账户用量的支配权，请按凭证级别妥善保管。
- 一类用途一把密钥。 按部门 / 业务线 / 成本中心拆分，既便于分账，也便于在某把密钥泄露时定向止损。
- 密钥只在服务端使用。 不要嵌入前端页面、移动端安装包或公开仓库；应放在服务端环境变量或受控的凭证管理设施中。
- 最小授权。 为密钥仅授权其确需调用的模型范围，缩小潜在影响面。
- 设置到期并定期轮换。 长期不过期的密钥风险更高；为密钥设置到期时间并周期性轮换。
- 泄露即处置。 一旦怀疑泄露，立即暂停该密钥止血，随后注销并重新申请。
- 保留唯一一次的明文。 密钥明文仅在创建时返回一次，请在创建当时即妥善保存，切勿事后尝试找回。