Meet YOLO26: next-gen vision AI.

Link to this sectionAPI 密钥#

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

Ultralytics Platform 设置个人资料选项卡 API 密钥部分及密钥列表

Link to this section创建 API key#

创建新 API 密钥：

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

Ultralytics Platform 设置个人资料选项卡创建 API 密钥对话框

Link to this section密钥名称#

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

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

Link to this section密钥显示#

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

Ultralytics Platform 设置个人资料选项卡 API 密钥创建复制对话框

复制你的密钥

创建后请复制你的密钥以便参考。密钥也会显示在密钥列表中——平台会解密并显示完整的密钥值，以便你可以随时复制。

Link to this section密钥格式#

API 密钥遵循以下格式：

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • 前缀：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远程训练#

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

软件包版本要求

平台集成需要 ultralytics>=8.4.60。更低版本无法与平台配合使用。

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 部分会显示该工作区的密钥。管理工作区 API 密钥需要编辑者或更高级别的角色。参阅 团队 获取角色详情。

Link to this section安全最佳实践#

Link to this section应该#

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

Link to this section不应该#

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

Link to this section密钥轮换#

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

  1. 创建同名新密钥
  2. 更新应用程序以使用新密钥
  3. 验证应用程序运行正常
  4. 撤销旧密钥
轮换计划

对于敏感应用程序，建议每 90 天轮换一次密钥。

Link to this section故障排除#

Link to this section密钥无效错误#

Error: Invalid API key

解决方案：

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

Link to this section权限被拒绝#

Error: Permission denied for this operation

解决方案：

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

Link to this section速率限制#

Error: Rate limit exceeded

解决方案：

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

Link to this section常见问题解答#

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 角色或更高权限的成员都可以创建限定在该工作区范围内的密钥。

贡献者
GLglenn-jocher8LAlaodouya1MYmykolaxboiko1SEsergiuwaxmann1LALaughing-q1

评论