Link to this sectionAPI Keys#

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

Link to this section创建 API 密钥#

创建新 API 密钥：

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

Link to this section密钥名称#

为你的密钥设置一个描述性名称：

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

Link to this section密钥显示#

创建完成后，密钥会显示一次：

Link to this section密钥格式#

API 密钥遵循以下格式：

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

Link to this section密钥安全性#

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

Link to this section使用 API 密钥#

Link to this section环境变量#

将密钥设置为环境变量：

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

Link to this sectionYOLO CLI#

使用 YOLO CLI 设置密钥：

yolo settings api_key="YOUR_API_KEY"

Link to this section在代码中#

在你的 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"

Link to this sectionHTTP 请求头#

在 API 请求中包含该密钥：

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

请参阅 REST API 参考 获取所有可用端点。

Link to this section远程训练#

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

pip install "ultralytics>=8.4.60"

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

请参阅 云训练 获取完整的远程训练指南。

Link to this section管理密钥#

Link to this section查看密钥#

所有密钥都列在 Settings > API Keys 选项卡中：

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

Link to this section撤销密钥#

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

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

Link to this section重新生成密钥#

如果密钥已被泄露：

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

Link to this section工作区 API 密钥#

API 密钥的作用域取决于当前活动的工作区：

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

在侧边栏切换工作区时，API Keys 部分会显示该工作区的密钥。需要 Editor（编辑者）或更高级别的角色才能管理工作区 API 密钥。有关角色详情，请参阅 Teams。

Link to this section安全最佳实践#

Link to this section建议#

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

Link to this section禁忌#

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

Link to this section密钥轮换#

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

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

Link to this section故障排除#

Link to this section无效密钥错误#

解决方案：

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

Link to this section权限被拒绝#

解决方案：

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

Link to this section速率限制#

解决方案：

1. 降低请求频率 — 请参阅 速率限制表 获取每个端点的限制
2. 使用 Retry-After 标头实现指数退避
3. 使用 专用端点 以获得无限的推理吞吐量

Link to this section常见问题解答 (FAQ)#

Link to this section我可以创建多少个密钥？#

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

Link to this section密钥会过期吗？#

密钥不会自动过期。它们在被撤销之前一直有效。为了安全起见，请考虑实施轮换机制。

Link to this section创建密钥后，我能再次查看它吗？#

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

Link to this section密钥是特定于区域的吗？#

密钥可以在不同区域使用，但仅能访问你账户所在区域的数据。

Link to this section我可以与团队成员共享密钥吗？#

更好的做法是：让每位团队成员创建自己的密钥。对于团队工作区，拥有 Editor 或更高级别角色的成员均可创建作用于该工作区的密钥。