API 密钥#

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

创建 API key#

创建新 API 密钥：

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

密钥名称#

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

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

密钥显示#

创建后，密钥会显示在一个确认对话框中：

密钥格式#

API 密钥遵循以下格式：

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

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

密钥安全#

• 密钥使用 AES-256-GCM encryption 存储，绝不以明文存储
• 前 11 个字符（ul_ 加上 8 个十六进制字符）用作显示前缀，以便在不暴露密钥的情况下识别它

使用 API 密钥#

环境变量#

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

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

使用 YOLO CLI 验证并保存密钥：

yolo login YOUR_API_KEY

使用 yolo logout 删除保存的密钥。

HTTP 标头#

在 API 请求中包含该密钥：

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

或者将其传递给 Python SDK（pip install "ultralytics-platform>=0.1.5"），它也会读取 ULTRALYTICS_API_KEY：

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

查看REST API 参考了解所有可用的端点。

远程训练#

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

开始前请安装或更新 Ultralytics 软件包：

pip install -U ultralytics

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

查看云端训练了解完整的远程训练指南。

管理密钥#

查看密钥#

所有密钥都列在 Settings > API Keys 标签页上：

每个密钥卡片显示密钥名称、可复制的密钥值、相对创建时间和撤销按钮。

撤销密钥#

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

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

重新生成密钥#

如果密钥已泄露：

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

工作区 API 密钥#

API 密钥的作用域限于当前激活的工作区：

• 个人工作区：密钥以你的个人账户身份进行身份验证
• 团队工作区：密钥以团队工作区所有者的身份进行身份验证，在该工作区中拥有完整的所有者权限

在侧边栏中切换工作区时，“API 密钥”部分会显示该工作区的密钥。由于工作区密钥带有所有者权限，因此只有工作区所有者才能创建、查看或撤销它。有关角色详情，请参阅 Teams。

On Premise 工作进程密钥#

连接 On Premise 主机会生成一个单独的工作进程密钥。工作进程密钥通过 On Premise 集成进行管理，而不是在此选项卡中管理，它们绝不会与你的 API 密钥一起列出，并且通过断开主机连接来撤销 —— 这也会取消该主机排队和运行的任务。

安全最佳实践#

应该#

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

不应该#

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

密钥轮换#

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

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

故障排除#

密钥无效错误#

Error: Invalid API key

解决方案：

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

权限被拒绝#

Error: Permission denied for this operation

解决方案：

1. 验证你是资源所有者或拥有相应的工作区访问权限
2. 检查密钥是否属于正确的工作区
3. 如果你在团队工作区中管理密钥，请确认你是工作区所有者 —— 其他角色会收到 Workspace owner access required
4. 如有必要，创建新密钥

速率限制#

Error: Rate limit exceeded

解决方案：

1. 减少请求频率 —— 请参阅 rate limit table 了解每个类别的限制
2. 使用 Retry-After 标头实现指数退避
3. 当你需要隔离的推理容量时，请使用专用端点

常见问题解答#