鉴权与安全

平台有两套相互独立的凭证体系，请勿混用：

两者都放在 Authorization: Bearer <key> 头中；用错凭证或基址会收到 401。

智能云 API Key（sk-heimori-）

所有 cloud.heimori.cn/v1 开放接口使用 Bearer Token 鉴权：

Authorization: Bearer sk-heimori-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 密钥在控制台「API 密钥」页创建与管理，可随时在列表中查看/复制完整密钥（服务端加密存储，鉴权仅比对哈希）。
• 一个账户可创建多个密钥，可分别设置产品范围（scopes）与限流参数，建议按应用/环境拆分密钥。
• WebSocket 接口（如实时语音识别）同样通过 Authorization 头携带密钥（浏览器端不支持自定义头时的替代方案见对应接口说明）。

Tengri AI 令牌（大模型与向量嵌入）

Tengri 大模型与向量嵌入使用独立的 Tengri AI 令牌：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 首次使用请在控制台「Tengri AI」区一键开通或绑定已有账号；令牌在「Tengri AI → API 令牌」创建、查看与禁用。
• 令牌可设置有效期、额度上限，安全规范与 sk-heimori- 密钥一致（仅服务端使用、定期轮换、泄露即禁用）。
• AI 产品的错误响应为 OpenAI 风格：{ "error": { "message": "...", "type": "..." } }。

鉴权失败的错误响应（智能云 API）

鉴权与权限错误使用统一错误结构（详见「错误码」）：

{
  "error": {
    "code": "invalid_api_key",
    "message": "API Key 无效",
    "requestId": "req_9f2b1c..."
  }
}

常见鉴权类错误码：invalid_api_key（401）、api_key_disabled（401）、api_key_expired（401）、scope_not_allowed（403）、account_suspended（403）。

请求追踪：X-Request-Id

每次调用（无论成功失败）的响应都携带 X-Request-Id 头，错误响应体中的 requestId 与其一致。它是平台侧定位单次请求的唯一凭据：

• 建议在调用方日志中记录 X-Request-Id；
• 向支持团队反馈问题时，请提供出错请求的 requestId 与大致时间。

密钥安全最佳实践

1. 只在服务端使用：密钥不要出现在浏览器、移动端安装包或公开仓库中；前端需求请经由你自己的后端转发。
2. 最小权限：按应用拆分密钥并限定产品范围，泄露影响面更小。
3. 设置限额：为每个密钥设置 QPS/并发/日调用上限，异常流量可被自动拦截。
4. 定期轮换：为密钥设置有效期并定期更换；离职交接、疑似泄露时立即在控制台禁用。
5. 余额告警：在费用中心设置余额告警阈值，避免因盗刷或超预期用量造成损失扩大。