REST API 参考

Q: How do I paginate large results?

大多数端点使用 limit 参数来控制每个请求返回的结果数量：活动和垃圾箱端点还支持 page 参数用于基于页面的分页：探索搜索端点使用 offset 而不是 page，固定页面大小为 20：

Q: How do I handle rate limits?

使用429响应中的Retry-After头来等待适当的时间：

Q: How do I find my model or dataset ID?

当您通过API创建资源时，会返回资源ID。您也可以在平台URL中找到它们：使用列表端点按名称搜索或按项目筛选。

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

Ultralytics 平台 API 概览

快速入门

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

交互式 API 文档

在Ultralytics 平台 API 文档中探索完整的交互式 API 参考。

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 密钥

前往 Settings > Profile （API密钥部分）
点击 Create Key
复制生成的密钥

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

授权头

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

Authorization: Bearer ul_your_api_key_here

API 密钥格式

API 密钥使用...格式 ul_ 后跟40个十六进制字符。请妥善保管您的密钥——切勿将其提交到版本控制或公开分享。

示例

cURLPythonJavaScript

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 请求/分钟	所有未在下面列出的端点（list、get、create、update、delete）
训练	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`	字符串	通过 slug 获取单个数据集
`limit`	整型	每页项目数（默认值：20，最大值：500）
`owner`	字符串	工作区所有者用户名

cURLPython

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 响应，其中包含最新数据集导出的签名下载 URL。

查询参数：

参数	类型	描述
`v`	整数	版本号（从1开始索引）。如果省略，则返回最新的（未缓存的）导出。

响应：

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

创建数据集版本

POST /api/datasets/{datasetId}/export

创建数据集的新的带编号版本快照。仅限所有者。该版本会捕获当前的图像数量、类别数量、标注数量和拆分分布，然后生成并存储一个不可变的 NDJSON 导出。

请求体：

{
    "description": "Added 500 training images"
}

所有字段都是可选的。该 description 字段是用户为版本提供的标签。

响应：

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

更新版本描述

PATCH /api/datasets/{datasetId}/export

更新现有版本的描述。仅限所有者。

请求体：

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

响应：

{
    "ok": 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

cURLPython

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 slug（小写字母数字/连字符）
`name`	字符串	否	显示名称（最多100个字符）
`description`	字符串	否	模型描述（最多1000字符）
`task`	字符串	否	任务类型 (detect, segment, 姿势估计, obb, classify)

模型文件上传

模型 .pt 文件上传单独处理。使用平台 UI 将模型文件拖放到项目中。

更新模型

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`	字符串	是	目标项目 slug
`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)

cURLPython

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

cURLPython

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, memoryGi, minInstances, maxInstances)

在指定区域创建一个专用的推理端点。该端点可通过唯一的URL进行全局访问。

区域选择

选择靠近您用户的区域以获得最低延迟。平台 UI 显示了所有 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`等）

cURLPython

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"]

支持的格式：

格式	值	用例
ONNX	`onnx`	跨平台推理
TorchScript	`torchscript`	PyTorch 部署
OpenVINO	`openvino`	Intel 硬件
TensorRT	`engine`	NVIDIA GPU 优化
CoreML	`coreml`	Apple 设备
TFLite	`tflite`	移动和嵌入式
TF SavedModel	`saved_model`	TensorFlow Serving
TF GraphDef	`pb`	TensorFlow 冻结图
PaddlePaddle	`paddle`	百度 PaddlePaddle
NCNN	`ncnn`	移动神经网络
Edge TPU	`edgetpu`	Google Coral 设备
TF.js	`tfjs`	浏览器推理
MNN	`mnn`	阿里巴巴移动推理
RKNN	`rknn`	瑞芯微 NPU
IMX	`imx`	索尼 IMX500 传感器
Axelera	`axelera`	Axelera AI 加速器
ExecuTorch	`executorch`	Meta 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

创建用于专业版订阅升级的结账会话。

正文：

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

字段	类型	必需	描述
`planId`	字符串	是	计划订阅（`pro`)
`billingCycle`	字符串	否	计费周期： `monthly` （默认）或 `yearly`
`owner`	字符串	否	用于工作区升级的团队用户名（需要管理员角色）

创建门户会话

POST /api/billing/portal-session

返回用于订阅管理的账单门户网址。

自动充值

当余额低于阈值时自动添加积分。

获取自动充值配置

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`	字符串	目标资产的 ID
`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`	完全访问权限，包括成员管理

请参阅团队，以了解 UI 中的角色详情。

更新成员角色

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 合规性端点。

GET /api/gdpr

查询参数：

参数	类型	描述
`jobId`	字符串	要检查的GDPR作业ID

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

启动导出或删除流程

POST /api/gdpr

正文：

{
    "action": "export"
}

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

团队工作区可选：

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

不可逆操作

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

错误代码

代码	HTTP 状态	描述
`UNAUTHORIZED`	401	API 密钥无效或缺失
`FORBIDDEN`	403	权限不足
`NOT_FOUND`	404	资源未找到
`VALIDATION_ERROR`	400	请求数据无效
`RATE_LIMITED`	429	请求过多
`INTERNAL_ERROR`	500	服务器错误

python 集成

为了更简单的集成，请使用Ultralytics python包，该包会自动处理身份验证、上传和实时指标流。

安装与设置

pip install ultralytics

验证安装：

yolo check

软件包版本要求

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

身份验证

CLI（推荐）环境变量代码中

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:// URI：

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

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

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

企业功能

自定义webhook端点在企业版计划中可用。Python SDK的训练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 SDK是一个便捷的封装器，增加了实时指标流和自动模型上传等功能。

是否有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

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

📅 创建于 2 个月前 ✏️ 更新于 5 天前