API 密钥

Ultralytics Platform API 密钥支持安全的编程访问，用于远程训练、推理和自动化。你可以为不同的使用场景创建带有 AES-256-GCM 加密的命名密钥。

创建 API 密钥

创建一个新的 API 密钥：

1. 前往 Settings > API Keys
2. 点击 Create Key
3. 输入密钥名称（例如：“Training Server”）
4. 点击 Create Key

密钥名称

为你的密钥指定一个描述性名称：

• training-server - 用于远程训练机器
• ci-pipeline - 用于 CI/CD 集成
• local-dev - 用于本地开发

密钥显示

创建后，该密钥仅显示一次：

密钥格式

API 密钥遵循以下格式：

• 前缀：ul_ 用于标识 Ultralytics 密钥
• 主体：40 个随机十六进制字符
• 总计：43 个字符

密钥安全

• 密钥存储采用 AES-256-GCM 加密
• 身份验证使用 SHA-256 哈希进行快速前缀查找和哈希比较
• 完整的密钥值绝不会以明文形式存储

使用 API 密钥

环境变量

将你的密钥设置为环境变量：

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI

使用 YOLO CLI 设置密钥：

yolo settings api_key="YOUR_API_KEY"

在代码中

在你的 Python 脚本中使用该密钥：

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"

HTTP 标头

在 API 请求中包含该密钥：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

查看 REST API Reference 获取所有可用端点。

远程训练

使用你的密钥启用指标流。

pip install "ultralytics>=8.4.35"

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

参阅 Cloud Training 获取完整的远程训练指南。

管理密钥

查看密钥

所有密钥均列在 Settings > API Keys 标签页下：

每个密钥卡片显示密钥名称、完整的解密密钥值（可复制）、相对创建时间以及撤销按钮。

撤销密钥

撤销已泄露或不再需要的密钥：

1. 在 API Keys 部分找到该密钥
2. 点击 Revoke（垃圾桶）按钮
3. 确认撤销

重新生成密钥

如果密钥已泄露：

1. 使用相同名称创建新密钥
2. 更新你的应用程序
3. 撤销旧密钥

工作区 API 密钥

API 密钥的作用域限制为当前处于活动状态的工作区：

• 个人工作区：密钥以你的个人账户身份进行验证
• 团队工作区：密钥在团队上下文中进行验证

在侧边栏切换工作区时，API Keys 部分会显示该工作区的密钥。管理工作区 API 密钥需要 Editor（编辑）或更高权限。查看 Teams 了解角色详情。

安全最佳实践

建议

• 将密钥存储在环境变量中
• 为不同的环境使用单独的密钥
• 及时撤销未使用的密钥
• 定期轮换密钥
• 使用描述性名称来标识密钥用途

不建议

• 将密钥提交到版本控制系统中
• 在不同应用程序之间共享密钥
• 在应用程序输出中记录密钥
• 将密钥嵌入客户端代码中

密钥轮换

为了安全起见，请定期轮换密钥：

1. 使用相同名称创建新密钥
2. 更新应用程序以使用新密钥
3. 验证应用程序是否正常工作
4. 撤销旧密钥

故障排除

密钥无效错误

解决方案：

1. 验证密钥是否已正确复制（包括 ul_ 前缀）
2. 检查密钥是否已被撤销
3. 确认环境变量已设置
4. 确保你使用的是 ultralytics>=8.4.35

权限不足

解决方案：

1. 验证你是否为资源所有者或具有相应的工作区访问权限
2. 检查密钥是否属于正确的工作区
3. 如有需要，创建一个新密钥

速率限制

解决方案：

1. 降低请求频率 — 查看 rate limit table 获取各端点的限制
2. 使用 Retry-After 标头实现指数退避
3. 使用 dedicated endpoint 以获得无限制的推理吞吐量

常见问题 (FAQ)

我可以创建多少个密钥？

API 密钥没有硬性限制。你可以根据不同应用程序和环境的需要创建任意数量的密钥。

密钥会过期吗？

密钥不会自动过期。它们在被撤销前一直有效。建议为了安全考虑定期轮换密钥。

创建后我可以查看我的密钥吗？

可以，完整的密钥值可在 Settings > API Keys 的密钥列表中查看。平台会解密并显示你的密钥，以便你随时复制。

密钥是特定于区域的吗？

密钥适用于所有区域，但仅能访问你账户所在区域的数据。

我可以与团队成员共享密钥吗？

更好的做法是：让每位团队成员创建自己的密钥。对于团队工作区，每位拥有编辑器 (Editor) 或更高角色的成员都可以创建属于该工作区的密钥。