API_KEY 认证使用指南

概述

AutoBox使用 API_KEY 作为主要的身份认证方式。每个 API_KEY 都与特定的用户账户关联，并具有独立的配额、权限和使用限制。

API_KEY 注册

1. 前提条件

在创建 API_KEY 之前，您需要：

拥有有效的 AutoBox用户账户
账户状态正常（未被禁用）
账户在有效期内

2. 创建 API_KEY

通过网页控制台创建

登录 AutoBox控制台
导航到 "API Key 管理" 页面
点击 "创建新的 API Key" 按钮
填写以下信息：
- 名称: API Key 的描述性名称
- 渠道: 选择适用的服务渠道（如 OpenAI、Claude 等）
- 分组: 设置 API Key 的分组标识
- 配额: 设置可用额度（可选）
- 过期时间: 设置过期日期（可选）
- 备注: 添加使用说明（可选）

通过 API 创建

POST /apikeys/create
Content-Type: application/x-www-form-urlencoded

token=your_user_token&name=测试API Key&channel=OpenAI&group=开发组&quota=1000&expired_time=20241231235959&comments=用于开发测试

响应示例:

{
  "detail": "API Key创建成功",
  "data": {
    "id": 1,
    "name": "测试API Key",
    "key": "ak-abcd1234efgh5678ijkl9012mnop3456",
    "channel": "OpenAI",
    "group": "开发组",
    "quota": 1000,
    "used_quota": 0,
    "created_time": "20240101120000",
    "expired_time": "20241231235959",
    "status": "启用",
    "comments": "用于开发测试"
  }
}

API_KEY 管理

1. 查看 API_KEY 列表

POST /apikeys/list
Content-Type: application/x-www-form-urlencoded

token=your_user_token&page=1&page_size=10&channel=OpenAI&status=启用

2. 更新 API_KEY

POST /apikeys/update
Content-Type: application/x-www-form-urlencoded

token=your_user_token&api_key_id=1&name=更新后的名称&quota=2000&status=启用

3. 删除 API_KEY

POST /apikeys/delete
Content-Type: application/x-www-form-urlencoded

token=your_user_token&api_key_id=1

API_KEY 使用方法

1. 在请求头中使用

Authorization: Bearer ak-your32characterapikeyhere

2. 验证流程

当您使用 API_KEY 调用接口时，系统会进行以下验证：

格式验证: 检查 API_KEY 格式是否正确（ak- 开头 + 32位字符）
存在性验证: 检查 API_KEY 是否存在于系统中
状态验证: 检查 API_KEY 状态是否为"启用"
用户验证: 检查关联用户是否有效
权限验证: 检查用户权限和账户状态
配额验证: 检查是否超出使用配额
过期验证: 检查 API_KEY 是否已过期

调用限制

1. 配额限制

每个 API_KEY 都有独立的配额限制：

总配额: 创建时设置的最大可用额度
已用配额: 当前已消耗的额度
剩余配额: 总配额 - 已用配额

2. 速率限制

每分钟请求数: 根据用户等级和 API_KEY 配置而定
并发请求数: 同时处理的最大请求数量
单次请求大小: 请求体的最大尺寸限制

3. 功能限制

不同渠道的 API_KEY 可能有不同的功能限制：

AutoBox: 支持所有任务类型
OpenAI: 仅支持 OpenAI 兼容接口
Claude: 仅支持 Claude 相关功能
自定义: 根据配置的权限范围

计费方式

1. 按使用量计费

Token 计费: 根据输入和输出 Token 数量计费
请求计费: 按 API 调用次数计费
时长计费: 按任务执行时间计费

2. 计费标准

服务类型	计费单位	价格
AutoBox 智能体	每次执行	¥1.0
n8n 工作流	每次执行	¥1.0
Dify 应用	每次执行	¥1.0
Coze 对话	每次执行	¥1.0

3. 计费周期

实时扣费: 每次 API 调用后立即扣除相应费用
账单周期: 按月生成详细账单
余额不足: 当配额用完时，API 调用将被拒绝

使用注意事项

1. 安全性

保密性: 不要在客户端代码、公共仓库或日志中暴露 API_KEY
权限最小化: 为不同用途创建不同的 API_KEY，设置适当的权限
定期轮换: 定期更新 API_KEY，特别是在怀疑泄露时
监控使用: 定期检查 API_KEY 的使用情况，发现异常及时处理

2. 性能优化

连接复用: 使用 HTTP 连接池减少连接开销
请求合并: 尽可能合并多个小请求为单个大请求
缓存策略: 对于相同的请求结果进行适当缓存
异步处理: 对于耗时任务使用异步接口

3. 错误处理

重试机制: 实现指数退避的重试策略
错误分类: 区分临时错误和永久错误
日志记录: 记录详细的错误信息用于调试
降级策略: 在服务不可用时的备用方案

4. 监控和告警

使用量监控: 监控 API_KEY 的使用量和剩余配额
错误率监控: 监控 API 调用的成功率和错误率
延迟监控: 监控 API 响应时间
配额告警: 在配额即将用完时发送告警

故障排除

常见错误及解决方案

401 Unauthorized
- 检查 API_KEY 格式是否正确
- 确认 API_KEY 是否有效且未过期
- 验证请求头格式是否正确
403 Forbidden
- 检查用户账户状态
- 确认 API_KEY 状态为"启用"
- 验证用户权限是否足够
429 Too Many Requests
- 检查是否超出速率限制
- 实现请求限流和重试机制
- 考虑升级配额或分散请求
500 Internal Server Error
- 检查请求参数是否正确
- 稍后重试请求
- 联系技术支持

最佳实践

环境变量: 使用环境变量存储 API_KEY
权限分离: 为不同环境（开发、测试、生产）使用不同的 API_KEY
定期审计: 定期审查 API_KEY 的使用情况和权限设置
文档记录: 记录每个 API_KEY 的用途和负责人
自动化管理: 使用脚本或工具自动化 API_KEY 的创建和管理