API 密钥和 IAM 规则

API 密钥是与 UniterRouter 进行身份验证的主要方法。本指南涵盖创建 API 密钥、管理它们以及配置 IAM 规则以进行细粒度访问控制。

概述

UniterRouter 提供全面的 API 密钥管理，具有以下功能：

• 基本 API 密钥管理：创建、列出、更新和删除 API 密钥
• 使用限额：为单个 API 密钥设置消费限额
• IAM 规则：对模型、提供商和定价进行细粒度访问控制
• 使用跟踪：监控 API 密钥使用情况和成本
• 状态管理：启用/禁用密钥而不删除

创建 API 密钥

通过控制台

目前，API 密钥只能通过控制台创建。

1. 在 UniterRouter 控制台中导航到你的项目
2. 进入 API 密钥 部分
3. 点击 创建 API 密钥
4. 为你的密钥提供描述
5. 可选择设置使用限额
6. 点击 创建

使用 API 密钥

获得 API 密钥后，在请求的 Authorization 头中使用它：

curl -X POST "https://api.uniterouter.ai/v1/chat/completions" \
  -H "Authorization: Bearer llmgtwy_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好！"}]
  }'

API 密钥管理

禁用/启用 API 密钥

你可以禁用 API 密钥以阻止其被使用，但密钥不会被删除，可以稍后重新启用。

使用限额

使用量按 API 密钥跟踪，显示在 API 密钥页面上。使用量包括 UniterRouter 额度的成本和使用你自己的提供商密钥时的使用量（如适用），让你完全了解每个密钥的总支出。

你可以为每个 API 密钥设置最大使用限额。当达到限额时，使用该密钥的请求将返回错误。

IAM 规则

IAM（身份访问管理）规则提供对 API 密钥可以访问的模型、提供商和定价层级的细粒度访问控制。

规则类型

模型访问规则

控制对特定模型的访问：

• 允许模型：只允许访问特定模型
• 拒绝模型：阻止访问特定模型

提供商访问规则

控制对特定提供商的访问：

• 允许提供商：只允许访问特定提供商
• 拒绝提供商：阻止访问特定提供商

定价规则

基于模型定价控制访问：

• 允许定价：设置允许的定价层级约束
• 拒绝定价：阻止特定定价层级
• 免费与付费：允许或拒绝访问免费与付费模型

错误处理

当 API 密钥遇到 IAM 规则违规时，API 返回特定的错误消息：

{
	"error": true,
	"status": 403,
	"message": "访问被拒绝：模型 gpt-4 不在允许的模型列表中"
}

常见错误场景：

• 模型不被 IAM 规则允许
• 提供商被 IAM 规则阻止
• 超出定价限制
• API 密钥被禁用或删除
• 达到使用限额

从旧密钥迁移

如果你有没有 IAM 规则的现有 API 密钥：

1. 向后兼容：现有密钥继续工作而不受限制
2. 渐进迁移：逐步添加 IAM 规则
3. 测试：在应用到生产环境之前在开发环境测试 IAM 规则
4. 监控：实施规则后监控访问被拒绝的错误