跳转至内容

REST API 参考

Ultralytics Platform 提供全面的 REST API，用于以编程方式访问数据集、模型、训练和部署。

Ultralytics API 概述

快速入门

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

API 概述

该API围绕核心平台资源进行组织：

graph LR
    A[API Key] --> B[Datasets]
    A --> C[Projects]
    A --> D[Models]
    A --> E[Deployments]
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]
    B -->|auto-annotate| B
资源描述关键操作
数据集标注图像集合CRUD、图片、标签、导出、克隆
项目培训工作区CRUD、克隆、图标
模型训练过的检查点CRUD操作、预测、下载、克隆、导出
部署专用推理端点CRUD操作、启动/停止、指标、日志、健康状态
导出格式转换任务创建、状态、下载
训练GPU 任务开始，状态，取消
账单积分与订阅余额、充值、支付方式
团队工作区协作成员、邀请、角色

身份验证

大多数API请求需要通过API密钥进行身份验证。公共接口（列出公共数据集、项目和模型）支持无需密钥的匿名读取访问。

获取 API 密钥

  1. 前往 Settings > Profile (API密钥部分)
  2. 点击 Create Key
  3. 复制生成的密钥

有关详细说明，请参阅API 密钥。

授权头

在所有请求中包含您的 API 密钥：

Authorization: Bearer ul_your_api_key_here

API密钥格式

API密钥采用以下格式： ul_ 后跟40个十六进制字符。请将密钥保密——切勿将其提交至版本控制系统或公开分享。

示例

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

基础 URL

所有 API 端点均使用：

https://platform.ultralytics.com/api

速率限制

该API采用双层速率限制系统，在防止滥用的同时确保合法使用不受限制：

  • 按API密钥— 对经过身份验证的请求，按API密钥实施限制
  • 按IP — 所有IP地址每分钟100次请求 /api/* 路径（适用于经过身份验证和未经身份验证的请求）

当受限时，API返回 429 带重试元数据：

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z

按 API 密钥限制

速率限制会根据调用的端点自动应用。高成本操作设有更严格的限制以防止滥用，而标准的CRUD操作则共享宽松的默认限制：

端点限制适用对象
默认值每分钟100个请求未在下方列出的所有端点（列出、获取、创建、更新、删除）
训练每分钟10次请求启动云端培训工作 (POST /api/training/start)
上传每分钟10次请求文件上传、签名URL和数据集摄取
预测每分钟20次请求共享模型推理POST /api/models/{id}/predict)
导出每分钟20次请求模型格式导出（POST /api/exports) 以及数据集 NDJSON 导出
下载每分钟30个请求模型权重文件下载 (GET /api/models/{id}/download)
专用无限制专用端点——您专属的服务，无API限制

每个类别都为每个API密钥设置独立计数器。例如，执行20次预测请求不会影响您每分钟100次的默认配额。

专用端点（无限制）

专用端点 是 不受API密钥速率限制当您将模型部署到专用端点时，对该端点URL（例如 https://predict-abc123.run.app/predict) 直接访问您的专用服务，不受平台速率限制。您支付的是计算资源费用，因此可获得无限吞吐量，上限取决于您端点的扩展配置。

处理速率限制

当你收到一封 429 状态码，等待 Retry-After （或直到 X-RateLimit-Reset在重试之前。参见 速率限制常见问题解答 用于指数退避算法的实现。

响应格式

成功响应

响应返回包含资源特定字段的JSON：

{
    "datasets": [...],
    "total": 100
}

错误响应

{
    "error": "Invalid dataset ID"
}
HTTP状态码意义
200成功
201创建日期
400无效请求
401需要身份验证
403权限不足
404资源未找到
409冲突（重复项）
429速率限制已超出
500服务器错误

数据集 AP

管理用于训练YOLO 标注图像集合。

列出数据集

GET /api/datasets

查询参数：

参数类型描述
username字符串按用户名筛选
slug字符串通过别名获取单个数据集
limit整型每页项目数（默认：20，最大：500）
owner字符串工作区所有者用户名
curl -H "Authorization: Bearer $API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

响应：

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

获取数据集

GET /api/datasets/{datasetId}

返回完整的数据集详细信息，包括元数据、类名称和分割计数。

创建数据集

POST /api/datasets

正文：

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "visibility": "private",
    "classNames": ["person", "car"]
}

支持的任务

有效 task 值： detect, segment, classify, pose, obb.

更新数据集

PATCH /api/datasets/{datasetId}

正文（部分更新）：

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

删除数据集

DELETE /api/datasets/{datasetId}

软删除数据集（移至回收站，30天内可恢复）。

克隆数据集

POST /api/datasets/{datasetId}/clone

创建包含所有图像和标签的数据集副本。仅可克隆公开数据集。

正文（所有字段均为可选）：

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "owner": "team-username"
}

导出数据集

GET /api/datasets/{datasetId}/export

返回包含数据集导出文件签名下载链接的JSON响应。

响应：

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

获取班级统计数据

GET /api/datasets/{datasetId}/class-stats

返回类别分布、位置热力图和维度统计数据。结果缓存时长最长为5分钟。

响应：

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

在数据集上训练模型

GET /api/datasets/{datasetId}/models

返回使用此数据集训练的模型。

响应：

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

自动标注数据集

POST /api/datasets/{datasetId}/predict

对数据集图像运行YOLO 以自动生成标注。使用选定模型为未标注图像预测标签。

正文：

字段类型必需描述
imageHash字符串是待标注图像的哈希值
modelId字符串否用于推理的模型ID
confidence浮点数否置信阈值（默认值：0.25）
iou浮点数否IoU （默认值：0.45）

数据集摄取

POST /api/datasets/ingest

创建一个数据集摄取作业，用于处理包含图像和标签的上传ZIP文件。

graph LR
    A[Upload ZIP] --> B[POST /api/datasets/ingest]
    B --> C[Process ZIP]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

数据集图像

图片列表

GET /api/datasets/{datasetId}/images

查询参数：

参数类型描述
split字符串按分割过滤： train, val, test
offset整型分页偏移量（默认值：0）
limit整型每页项目数（默认：50，最大：5000）
sort字符串排序顺序： newest, oldest, name-asc, name-desc, size-asc, size-desc, labels-asc, labels-desc
hasLabel字符串按标签状态筛选 (true 或 false)
hasError字符串按错误状态筛选 (true 或 false)
search字符串按文件名或图像哈希值搜索
includeThumbnails字符串包含签名的缩略图URL（默认： true)
includeImageUrls字符串包含已签名的完整图像URL（默认： false)

获取签名图像URL

POST /api/datasets/{datasetId}/images/urls

获取一批图像哈希值的签名URL（用于在浏览器中显示）。

删除图片

DELETE /api/datasets/{datasetId}/images/{hash}

获取图像标签

GET /api/datasets/{datasetId}/images/{hash}/labels

返回特定图像的注释和类名。

更新图片标签

PUT /api/datasets/{datasetId}/images/{hash}/labels

正文：

{
    "labels": [{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] }]
}

坐标格式

边界框采用YOLO 格式： [x_center, y_center, width, height] 其中所有值都在0到1之间。

批量图像操作

在数据集内将图像在分割集（训练集/验证集/测试集）之间移动：

PATCH /api/datasets/{datasetId}/images/bulk

批量删除图片：

DELETE /api/datasets/{datasetId}/images/bulk

项目 AP

管理将模型分组的培训工作区。

列出项目

GET /api/projects

查询参数：

参数类型描述
username字符串按用户名筛选
limit整型每页项目数
owner字符串工作区所有者用户名

获取项目

GET /api/projects/{projectId}

创建项目

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

更新项目

PATCH /api/projects/{projectId}

删除项目

DELETE /api/projects/{projectId}

软删除项目（移至回收站）。

克隆项目

POST /api/projects/{projectId}/clone

项目图标

上传项目图标（多部分表单，需包含图像文件）：

POST /api/projects/{projectId}/icon

移除项目图标：

DELETE /api/projects/{projectId}/icon

模型 AP

在项目内管理训练好的模型检查点。

列出模型

GET /api/models

查询参数：

参数类型必需描述
projectId字符串是项目ID（必填）
fields字符串否字段集： summary, charts
ids字符串否以逗号分隔的模型ID
limit整型否最大结果数（默认20，最大100）

已完成模型列表

GET /api/models/completed

返回已完成训练的模型（用于模型选择器和部署）。

获取模型

GET /api/models/{modelId}

创建模型

POST /api/models

JSON正文：

字段类型必需描述
projectId字符串是目标项目ID
slug字符串否URL 路径名（小写字母数字/连字符）
name字符串否显示名称（最多100个字符）
description字符串否模型描述（最多1000字符）
task字符串否任务类型（detect、segment、姿势估计、旋转框检测、classify）

模型文件上传

模型 .pt 文件上传采用独立处理机制。请通过平台界面将模型文件拖拽至项目中。

更新模型

PATCH /api/models/{modelId}

删除模型

DELETE /api/models/{modelId}

下载模型文件

GET /api/models/{modelId}/files

返回模型文件的签名下载 URL。

克隆模型

POST /api/models/{modelId}/clone

将公共模型克隆到您其中一个项目中。

正文：

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}
字段类型必需描述
targetProjectSlug字符串是目标项目别名
modelName字符串否克隆模型的名称
description字符串否模型描述
owner字符串否团队用户名（用于工作区克隆）

追踪下载

POST /api/models/{modelId}/track-download

追踪模型下载分析数据。

运行推理

POST /api/models/{modelId}/predict

多部分表单：

字段类型描述
file文件图像文件（JPEG、PNG、WebP）
conf浮点数置信阈值（默认值：0.25）
iou浮点数IoU （默认值：0.7）
imgsz整型图像尺寸（像素）（默认：640）
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

响应：

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

获取预测代币

POST /api/models/{modelId}/predict/token

获取用于直接预测请求的短效令牌。该令牌可绕过API代理，实现客户端应用程序的低延迟推理。

预热模型

POST /api/models/{modelId}/predict/warmup

预加载模型以加快首次推理速度。在运行预测前调用此方法，可避免初始请求出现延迟。

训练 AP

启动、监控和取消云训练任务。

graph LR
    A[POST /training/start] --> B[Job Created]
    B --> C{Training}
    C -->|progress| D[GET /models/id/training]
    C -->|cancel| E[DELETE /models/id/training]
    C -->|complete| F[Model Ready]
    F --> G[Deploy or Export]

开始训练

POST /api/training/start

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo11n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

GPU

可用的GPU 包括 rtx-4090, a100-80gb-pcie, a100-80gb-sxm, h100-sxm, rtx-pro-6000以及其他。参见 云端训练 查看完整价格列表。

获取训练状态

GET /api/models/{modelId}/training

返回模型的当前训练任务状态、指标和进度。

取消训练

DELETE /api/models/{modelId}/training

终止正在运行的计算实例，并将作业标记为已取消。

部署 AP

创建和管理专用推理端点。

graph LR
    A[Create] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

列出部署

GET /api/deployments

查询参数：

参数类型描述
modelId字符串按模型筛选
status字符串按状态筛选
limit整型最大结果数（默认：20，最大：100）
owner字符串工作区所有者用户名

创建部署

POST /api/deployments

正文：

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}
字段类型必需描述
modelId字符串是要部署的模型ID
name字符串是部署名称
region字符串是部署区域
resources对象否资源配置（cpu、内存Gi、最小实例数、最大实例数）

在指定区域创建专用的推理端点。该端点可通过唯一URL实现全球访问。

区域选择

选择距离用户最近的区域以获得最低延迟。平台界面显示所有43个可用区域的延迟估计值。

获取部署

GET /api/deployments/{deploymentId}

删除部署

DELETE /api/deployments/{deploymentId}

启动部署

POST /api/deployments/{deploymentId}/start

恢复已暂停的部署。

停止部署

POST /api/deployments/{deploymentId}/stop

暂停正在运行的部署（停止计费）。

健康检查

GET /api/deployments/{deploymentId}/health

返回部署端点的健康状态。

在部署环境中运行推理

POST /api/deployments/{deploymentId}/predict

将图像直接发送至部署端点进行推理。功能上等同于模型预测，但通过专用端点路由以实现更低延迟。

多部分表单：

字段类型描述
file文件图像文件（JPEG、PNG、WebP）
conf浮点数置信阈值（默认值：0.25）
iou浮点数IoU （默认值：0.7）
imgsz整型图像尺寸（像素）（默认：640）

获取指标

GET /api/deployments/{deploymentId}/metrics

返回请求计数、延迟和错误率指标，并附带微型图表数据。

查询参数：

参数类型描述
range字符串时间范围： 1h, 6h, 24h (默认)， 7d, 30d
sparkline字符串设置为 true 为仪表板视图优化微型图数据

获取日志

GET /api/deployments/{deploymentId}/logs

查询参数：

参数类型描述
severity字符串逗号分隔过滤器： DEBUG, INFO, WARNING, ERROR, CRITICAL
limit整型条目数量（默认：50，最大：200）
pageToken字符串来自先前响应的分页令牌

监控API

聚合指标

GET /api/monitoring

返回所有用户部署的汇总指标：总请求数、活跃部署数、错误率和平均延迟。

导出 AP

将模型转换为适用于边缘部署的优化格式。

列出导出

GET /api/exports

查询参数：

参数类型描述
modelId字符串模型ID（必填）
status字符串按状态筛选
limit整型最大结果数（默认：20，最大：100）

创建导出

POST /api/exports

正文：

字段类型必需描述
modelId字符串是源模型ID
format字符串是导出格式（见下表）
gpuType字符串条件性需要时 format 是 engine (TensorRT)
args对象否导出参数 (imgsz, half, dynamic等等
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

支持的格式：

格式值用例
ONNXonnx跨平台推理
TorchScripttorchscriptPyTorch 部署
OpenVINOopenvinoIntel
TensorRTengineNVIDIA GPU
CoreMLcoreml苹果设备
TFLitetflite移动与嵌入式
TF SavedModelsaved_modelTensorFlow
TF GraphDefpbTensorFlow 图
PaddlePaddlepaddle百度PaddlePaddlePaddle
NCNNncnn移动神经网络
Edge TPUedgetpuGoogle 设备
TF.jstfjs浏览器推断
MNNmnn阿里巴巴移动端推理
RKNNrknn瑞芯微 NPU
IMXimx索尼IMX500传感器
AxeleraaxeleraAxelera AI加速器
ExecuTorchexecutorchMeta ExecuTorch 运行时

获取导出状态

GET /api/exports/{exportId}

取消导出

DELETE /api/exports/{exportId}

轨道导出下载

POST /api/exports/{exportId}/track-download

活动 AP

track 并管理您账户的活动事件。

列出活动

GET /api/activity

查询参数：

参数类型描述
limit整型页面大小（默认：20，最大：100）
page整型页码（默认值：1）
archived布尔值true 存档选项卡， false 收件箱
search字符串事件字段中的不区分大小写搜索

标记事件已读

POST /api/activity/mark-seen

正文：

{
    "all": true
}

或传递特定ID：

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

归档事件

POST /api/activity/archive

正文：

{
    "all": true,
    "archive": true
}

或传递特定ID：

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

回收站 AP

管理软删除资源（30 天保留期）。

列出回收站

GET /api/trash

查询参数：

参数类型描述
type字符串过滤器： all, project, dataset, model
page整型页码（默认值：1）
limit整型每页项目数（默认：50，最大：200）
owner字符串工作区所有者用户名

恢复项目

POST /api/trash

正文：

{
    "id": "item_abc123",
    "type": "dataset"
}

永久删除项目

DELETE /api/trash

正文：

{
    "id": "item_abc123",
    "type": "dataset"
}

不可逆转

永久删除无法撤销。该资源及所有关联数据都将被移除。

清空回收站

DELETE /api/trash/empty

永久删除回收站中的所有项目。

账单 AP

管理积分、订阅和支付方式。

货币单位

账单金额使用分（creditsCents) 哪里 100 = $1.00.

获取余额

GET /api/billing/balance

查询参数：

参数类型描述
owner字符串工作区所有者用户名

响应：

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

获取使用情况摘要

GET /api/billing/usage-summary

返回套餐详情、限制和使用指标。

获取交易

GET /api/billing/transactions

返回交易记录（按时间倒序排列）。

查询参数：

参数类型描述
owner字符串工作区所有者用户名

创建结账会话

POST /api/billing/checkout-session

正文：

{
    "amount": 25,
    "owner": "team-username"
}
字段类型必需描述
amount数字是金额（美元）（5-1000美元）
owner字符串否团队用户名用于工作区充值（需管理员角色）

创建用于信用购买的结账会话。

创建订阅结账

POST /api/billing/subscription-checkout

创建Pro订阅升级的结账会话。

正文：

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}
字段类型必需描述
planId字符串是计划订阅（pro)
billingCycle字符串否计费周期： monthly (默认) 或 yearly
owner字符串否团队用户名用于工作区升级（需具备管理员角色）

创建门户会话

POST /api/billing/portal-session

返回订阅管理计费门户的URL。

自动充值

当余额低于阈值时自动添加信用额度。

获取自动充值配置

GET /api/billing/auto-topup

查询参数：

参数类型描述
owner字符串工作区所有者用户名

更新自动充值配置

PATCH /api/billing/auto-topup

正文：

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

支付方式

列出支付方式

GET /api/billing/payment-methods

创建设置意图

POST /api/billing/payment-methods/setup

返回用于添加新支付方式的客户端密钥。

设置默认支付方式

POST /api/billing/payment-methods/default

正文：

{
    "paymentMethodId": "pm_123"
}

更新账单信息

PATCH /api/billing/payment-methods

正文：

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

删除支付方式

DELETE /api/billing/payment-methods/{id}

存储 AP

获取存储信息

GET /api/storage

响应：

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

重新计算存储空间

POST /api/storage

触发存储使用情况的重新计算。

上传API

直接文件上传采用两步签名URL流程。

获取签名上传URL

POST /api/upload/signed-url

请求签名URL以将文件直接上传至云存储。该签名URL可绕过API服务器进行大文件传输。

正文：

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}
字段类型描述
assetType字符串资产类型： models, datasets, images, videos
assetId字符串目标资产的标识符
filename字符串原始文件名
contentType字符串MIME类型
totalBytes整型文件大小（字节）

响应：

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

完成上传

POST /api/upload/complete

通知平台文件上传已完成，以便其开始处理。

正文：

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

AP 密钥 AP

列出 AP 密钥

GET /api/api-keys

创建 AP 密钥

POST /api/api-keys

正文：

{
    "name": "training-server"
}

删除 AP 密钥

DELETE /api/api-keys

查询参数：

参数类型描述
keyId字符串要撤销的API密钥ID

例子：

curl -X DELETE \
  -H "Authorization: Bearer $API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

团队与成员 API

管理团队、成员和邀请，实现工作空间协作。

列出团队

GET /api/teams

创建团队

POST /api/teams/create

正文：

{
    "username": "my-team",
    "fullName": "My Team"
}

列出成员

GET /api/members

返回当前工作区的成员。

邀请成员

POST /api/members

正文：

{
    "email": "user@example.com",
    "role": "editor"
}

成员角色

角色权限
viewer对工作区资源的只读访问权限
editor创建、编辑和删除资源
admin完整访问权限，包括会员管理

有关用户界面中的角色详情，请参阅Teams。

更新成员角色

PATCH /api/members/{userId}

移除成员

DELETE /api/members/{userId}

转让所有权

POST /api/members/transfer-ownership

邀请函

接受邀请

POST /api/invites/accept

获取邀请信息

GET /api/invites/info

查询参数：

参数类型描述
token字符串邀请令牌

撤销邀请

DELETE /api/invites/{inviteId}

重新发送邀请

POST /api/invites/{inviteId}/resend

探索 API

搜索公开内容

GET /api/explore/search

查询参数：

参数类型描述
q字符串搜索查询
type字符串资源类型： all (默认)， projects, datasets
sort字符串排序顺序： stars (默认)， newest, oldest, name-asc, name-desc, count-desc, count-asc
offset整型分页偏移量（默认值：0）。每页返回20条结果。
GET /api/explore/sidebar

为“探索”侧边栏返回精选内容。

用户与设置 API

通过用户名获取用户

GET /api/users

查询参数：

参数类型描述
username字符串要查询的用户名

关注或取消关注用户

PATCH /api/users

正文：

{
    "username": "target-user",
    "followed": true
}

检查用户名可用性

GET /api/username/check

查询参数：

参数类型描述
username字符串待验证用户名
suggest布尔值可选： true 如采纳，请附建议

设置

GET /api/settings
POST /api/settings

获取或更新用户个人资料设置（显示名称、个人简介、社交链接等）。

个人资料图标

POST /api/settings/icon
DELETE /api/settings/icon

上传或移除个人资料头像。

入职培训

POST /api/onboarding

完整的入职流程（设置数据区域、用户名）。

GDPR AP

用于数据导出和删除的 GDPR 合规性端点。

获取GDPR职位状态

GET /api/gdpr

查询参数：

参数类型描述
jobId字符串GDPR职位ID用于核查

返回作业状态。对于已完成的导出作业，响应包含一个 downloadUrl.

开始导出或删除流程

POST /api/gdpr

正文：

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

团队工作区可选功能：

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

不可逆操作

账户删除是永久性的，无法撤销。所有数据、模型和部署都将被删除。

错误代码

代码HTTP状态码描述
UNAUTHORIZED401API 密钥无效或缺失
FORBIDDEN403权限不足
NOT_FOUND404资源未找到
VALIDATION_ERROR400请求数据无效
RATE_LIMITED429请求过多
INTERNAL_ERROR500服务器错误

Python

为简化集成流程，请Ultralytics Python 该包可自动处理身份验证、数据上传及实时指标流传输。

安装与设置

pip install ultralytics

验证安装：

yolo check

软件包版本要求

平台集成需要ultralytics版本≥8.4.14。较低版本将无法与平台兼容。

身份验证

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

使用平台数据集

包含以下内容的参考数据集： ul:// 统一资源标识符：

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/your-dataset",
    epochs=100,
    imgsz=640,
)

URI格式：

模式描述
ul://username/datasets/slug数据集
ul://username/project-name项目
ul://username/project/model-name特定型号
ul://ultralytics/yolo26/yolo26n官方型号

推送至平台

将结果发送至平台项目：

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://your-username/my-project",
    name="experiment-1",
)

同步内容：

  • 训练指标（实时）
  • 最终模型权重
  • 验证图
  • 控制台输出
  • 系统指标

API示例

从平台加载模型：

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

运行推理：

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

导出模型：

# Export to ONNX
model.export(format="onnx", imgsz=640, half=True)

# Export to TensorRT
model.export(format="engine", imgsz=640, half=True)

# Export to CoreML
model.export(format="coreml", imgsz=640)

验证：

metrics = model.val(data="ul://username/my-dataset")

print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")

Webhooks

Webhook通过HTTP POST回调通知您的服务器平台事件：

事件描述
training.started训练任务已启动
training.epoch周期已完成
training.completed训练完成
training.failed训练失败
export.completed导出就绪

企业功能

自定义 webhook 端点仅在企业版计划中可用。Python 的训练 webhook 在所有计划中均可自动运行。

常见问题

如何对大量结果进行分页？

大多数端点使用一个 limit 参数用于控制每次请求返回的结果数量：

curl -H "Authorization: Bearer $API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

活动和垃圾端点还支持一个 page 基于页面的分页参数：

curl -H "Authorization: Bearer $API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

探索搜索端点使用 offset 代替 page固定页面尺寸为20：

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&sort=stars"

我可以在没有SDK的情况下使用API吗？

是的，所有功能均可通过REST访问。Python 作为便捷封装层，额外提供了实时指标流传输和自动模型上传等功能。

是否有API客户端库？

目前，请使用 Ultralytics Python 包或直接发送 HTTP 请求。其他语言的官方客户端库正在计划中。

我如何处理速率限制？

使用 Retry-After 429响应的头部信息，用于等待适当的时间：

import time

import requests


def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

如何查找我的模型或数据集ID？

通过API创建资源时会返回资源ID。您还可以在平台URL中找到它们：

https://platform.ultralytics.com/username/project/model-name
                                  ^^^^^^^^ ^^^^^^^ ^^^^^^^^^^
                                  username project   model

使用列表端点按名称搜索或按项目筛选。



📅 创建于 1 个月前 ✏️ 更新于 5 天前
glenn-jochersergiuwaxmannLaughing-q

评论