API 密钥

API 密钥是调用 Amux 的唯一凭据。密钥等同于调用身份：任何持有它的人都能以你的名义发起调用并产生费用，应按对待密码的标准保管。

密钥绑定在工作区上，其产生的费用记入该工作区所属账户。

创建与查看#

在控制台的 API 密钥 页面创建密钥。创建时只需填写名称，其余配置均可随时修改。

密钥创建后仍可在该页面再次查看完整内容，无需重新生成。少量在可取回存储上线之前签发的历史密钥只保留前缀，无法再次查看完整内容；需要时重新创建一把即可。

建议按项目或按用途分别创建密钥：用量、费用与日志均按密钥统计，同一把密钥下的请求事后无法再拆分归属。

状态#

密钥泄露时应立即吊销。吊销只阻止后续调用，无法撤销已经发生的上游成本。

额度限制#

密钥上可以设置四项额度上限，任一项达到即拒绝后续调用：

留空表示该项不限制。

周期按 UTC 计算，不随账户或浏览器时区变化。

限额只统计实际扣费。上游报错产生的成本由平台承担，不计入你的限额。

额度可以在三个位置设置，同时生效、任一档到顶即拒绝：

工作区那一档对该工作区里的每一把密钥都生效，在用量页可以看到它的上限与当前用量。

可调用模型#

可以为密钥指定一份模型白名单，指定之后该密钥只能调用列表中的模型。留空表示不限制。

候选模型受上级的限制与该密钥自己的货源范围、指定供应商共同影响：

• 组织可以给整个工作区限定一份模型名单，密钥只能在其中再收窄；
• 货源范围与指定供应商收窄之后，不在其范围内的模型不再出现在候选列表中。

已经选中、但后来落在范围之外的模型会标注「不在当前范围」，不会被静默删除。

带上密钥请求 GET /v1/models 时，返回的就是这把密钥实际能调用的那些模型； 不带密钥则返回全部。详见 列出模型。

路由#

密钥可以跟随上级，也可以自定义。自定义时可设置四项：

约束类配置只能在上级（账户、以及组织工作区那一层）的基础上收窄，不能放宽。 例如工作区已将货源范围限定为「仅官方质量层」，密钥无法再把低价层纳入候选—— 此时密钥设置里那一项会直接显示为已限定的结果，不再提供选择。

「跟随上级」与「自定义」的区别不在于受不受上级约束——两种模式下上级的限制 都照常生效。它决定的是：排序策略跟不跟着上级变、要不要再收窄、以及请求级 后缀锁不锁。

「指定」与「优先」的区别在于是否改变候选池：

• 指定供应商会把候选池缩小到名单之内。名单之外的模型将变得不可调用，界面会给出覆盖率提示，说明当前名单覆盖了多少个可调用模型。
• 优先供应商不改变候选池，只调整顺序。优先的几家全部不可用时，请求仍会落到其余供应商，因此永远不会让某个模型变得不可调用。

两者可以同时使用，语义为「仅限 A、B、C，其中优先 A」。

允许请求覆盖策略#

密钥单独配置路由后，默认锁定请求级的策略后缀：调用方使用 模型:@price 这类后缀时会直接返回错误，而不是被静默忽略。

需要保留单次覆盖余地时，在密钥设置中开启「允许请求覆盖策略」。典型场景是一把密钥服务多个任务，其中大部分为批处理（默认价格优先），个别接口需要低延迟。

请求后缀始终只能改变排序策略，无法放宽货源范围或指定供应商名单。

完整的逐层合并规则见路由与故障转移。

可见范围#

密钥记录创建者。在工作区中：

• 工作区管理员可以查看和管理该工作区的全部密钥
• 工作区成员只能查看和管理自己创建的密钥

缺少归属人的历史密钥仅对工作区管理员可见。角色划分见角色与权限。

任务回调签名#

异步生成任务（/v1/tasks）支持在任务进入终态时回调你指定的地址。任何知道该地址的人都可以伪造一条「任务成功」的通知，而接收方通常会据此发货或扣账，因此 Amux 会对回调请求签名，你必须校验它。

签名密钥按工作区派生，一个工作区一把，由工作区管理员在 API 密钥页面查看。它与调用用的 API 密钥是两样东西，用途不同，不可互换。

回调的载荷形状、Amux-Signature 头的格式、重试退避与去重要求，见 API 参考中 POST /v1/tasks 的说明。

⚠️ 未配置签名密钥时平台不发送回调，而不是发送一条不带签名的。一条发不出去的回调是可见的故障，一条不带签名的回调是安全漏洞。

安全建议#

• 不要把密钥写进前端代码或提交到版本库。 泄露后任何人都可以用它调用并消耗你的余额
• 按用途拆分密钥，便于在出问题时只吊销受影响的那一把
• 为生产密钥设置额度上限，把单次事故的损失限制在可接受范围内
• 配置余额提醒，在异常消耗发生时尽早收到通知，详见充值与自动充值
• 定期检查「最近使用」，长期未使用的密钥应吊销

因密钥泄露产生的调用与费用由账户持有人承担，详见服务条款。

相关#

• 路由与故障转移 —— 三层配置的合并规则
• 角色与权限 —— 谁能创建和管理密钥
• 计费概览 —— 费用如何产生与归属