Link to this sectionREST API 参考#

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

Ultralytics Platform API 概览

快速入门

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

交互式 API 文档

在 Ultralytics Platform API 文档中浏览完整的交互式 API 参考。

Link to this sectionAPI 概览#

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

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    A --> D[Models]:::proc
    A --> E[Deployments]:::proc
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]:::proc
    B -->|auto-annotate| B

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

资源	描述	关键操作
数据集	标注图像集	CRUD、图像、标签、导出、版本、克隆
项目	训练工作区	CRUD、克隆、图标
模型	已训练的检查点	CRUD、预测、下载、克隆、导出
部署	专用推理端点	CRUD、启动/停止、指标、日志、健康状态
导出	格式转换任务	创建、状态、下载
训练	云端 GPU 训练任务	启动、状态、取消
账单	额度与使用情况	余额、用量、交易记录
团队	工作区协作	工作区、成员、角色

Link to this section身份验证#

资源 API 使用 API-key 进行身份验证，包括数据集类和拆分管理、克隆、训练、导出、部署以及支持的账户读取操作。公共端点在有说明的情况下支持匿名访问。基于浏览器的应用程序路由不包含在内。

Link to this section获取 API Key#

前往 Settings > API Keys
点击 Create Key
复制生成的密钥

参阅 API Keys 以获取详细说明。

Link to this section授权请求头#

在所有请求中包含你的 API key：

Authorization: Bearer YOUR_API_KEY

API Key 格式

API key 使用 ul_ 开头，后跟 40 位十六进制字符。请妥善保管你的密钥——切勿将其提交到版本控制系统或公开发布。

Link to this section示例#

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

Link to this sectionBase URL#

所有 API 端点均使用：

https://platform.ultralytics.com/api

Link to this section速率限制#

该 API 对每个 API key 实施速率限制（滑动窗口，由 Upstash Redis 提供支持），以防止滥用，同时确保合法使用的不受限制。匿名流量还会受到 Vercel 平台级滥用控制的额外保护。

当受到限流时，API 会返回 429 状态码以及重试元数据：

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

Link to this section每个 API Key 的限制#

速率限制根据所调用的端点自动应用。高负载操作有更严格的限制以防止滥用，而标准 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}/files`)
专用	无限	专用端点 — 你自己的服务，无 API 限制

每个类别在每个 API key 下都有独立的计数器。例如，进行 20 次预测请求不会影响你 100 次/分钟的默认限额。

Link to this section专用端点（无限）#

专用端点 不受 API key 速率限制的影响。当你将模型部署到专用端点时，针对该端点 URL（例如 https://predict-abc123.run.app/predict）的请求会直接发送到你的专用服务，而不会受到平台的速率限制。你支付的是计算费用，因此你获得的是基于专用服务配置的吞吐量，而非共享的 API 限制。

处理速率限制

当你收到 429 状态码时，请等待 Retry-After 指定的时间（或直到 X-RateLimit-Reset）后再进行重试。查看速率限制 FAQ 以获取指数退避实现示例。

Link to this section响应格式#

Link to this section成功响应#

响应返回 JSON，其中包含特定于资源的字段：

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

Link to this section错误响应#

{
    "error": "Dataset not found"
}

HTTP 状态	含义
`200`	成功
`201`	已创建
`400`	请求无效
`401`	需要身份验证
`403`	权限不足
`404`	资源未找到
`409`	冲突（重复）
`429`	超出速率限制
`500`	服务器错误

Link to this section数据集 API#

创建、浏览并管理用于训练 YOLO 模型的带标签图像数据集。请参阅数据集文档。

Link to this section列出数据集#

GET /api/datasets

查询参数：

参数	类型	描述
`username`	string	按用户名过滤
`limit`	int	每页项目数（默认：1000，最大：1000）
`owner`	string	工作区所有者用户名
`includeImageUrls`	布尔值	包含已签名的全尺寸示例图像 URL（默认：`false`）
`includeSamples`	布尔值	设置为 `false` 以忽略示例图像并减小响应大小。

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

响应：

{
    "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"
}

Link to this section获取数据集#

GET /api/datasets/{datasetId}

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

Pass username when {datasetId} is a dataset slug rather than an ID.

Link to this section创建数据集#

POST /api/datasets

请求体：

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

支持的任务

有效的 task 值：detect、segment、semantic、classify、pose、obb。

响应：

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Link to this section更新数据集#

PATCH /api/datasets/{datasetId}

请求体（部分更新）：

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

Link to this section数据集图标#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

上传一个最大 5 MB 的 WebP 图标作为 multipart 表单字段 image，或移除当前图标。

Link to this section克隆数据集#

POST /api/datasets/{datasetId}/clone

创建公共、自有或可编辑工作区数据集的副本，包含所有图像和标签。

可选主体（所有字段均为可选）：

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

Link to this section导出数据集#

GET /api/datasets/{datasetId}/export

返回一个包含最新数据集导出的带签名下载 URL 的 JSON 响应。

查询参数：

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

响应：

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

Link to this section创建数据集版本#

POST /api/datasets/{datasetId}/export

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

请求体：

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

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

响应：

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

Link to this section更新版本描述#

PATCH /api/datasets/{datasetId}/export

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

请求体：

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

响应：

{
    "ok": true
}

Link to this section还原数据集版本#

POST /api/datasets/{datasetId}/restore

从保存的版本重建数据集的图像、注释和类，无需复制图像字节。

{
    "version": 2
}

Link to this section获取类别统计信息#

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
}

Link to this section管理类别#

合并类别（将标注从源类别重新分配给目标类别，然后移除源类别）：

POST /api/datasets/{datasetId}/classes/merge

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

类 ID 是按位置排列的，因此合并操作不是幂等的。请在重试前重新获取数据集。

删除类别：

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Link to this section重新分配拆分#

POST /api/datasets/{datasetId}/splits/redistribute

在训练、验证和测试拆分之间随机重新分配图像。百分比总和必须为 100。

{
    "train": 80,
    "val": 20,
    "test": 0
}

Link to this section数据集嵌入#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET 返回当前的 UMAP 分析摘要和活跃任务状态；POST 将嵌入分析任务加入队列；DELETE 取消活跃任务。

Link to this section图像聚类#

GET /api/datasets/{datasetId}/images/clustering

返回聚类散点图视图的 UMAP 2D 布局及每张图像的元数据（分页且受速率限制）。

Link to this section获取在该数据集上训练的模型#

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
}

Link to this section自动标注数据集#

POST /api/datasets/{datasetId}/predict

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

请求体：

字段	类型	必填	描述
`imageHash`	string	是	要标注图像的哈希值
`modelId`	string	否	用于推理的模型，格式为 `ul://` URI（例如 `ul://username/project/model`）。如果省略，则使用数据集的任务特定默认模型。
`confidence`	float	否	置信度阈值（默认：0.25）
`iou`	float	否	IoU 阈值（默认：0.7）

Link to this section数据集摄入#

POST /api/datasets/ingest

为现有数据集创建一个数据集导入作业。目标数据集始终在 JSON 正文中作为 datasetId 传递，而不是在 URL 路径中传递。

请求正文需要 datasetId 以及 sessionId（已上传存档的上传会话）或 sourceUrl（远程 ZIP、TAR、TAR.GZ、TGZ 或 NDJSON URL）中的其中一个。添加可选的 targetSplit（train、val 或 test）以覆盖存档的拆分结构。

For uploaded archives, the upload session is already bound to the dataset by the assetId passed to POST /api/upload/signed-url; ingest validates that assetId matches the body datasetId. Optional classMapping entries map each incoming class name to an existing zero-based class index, a class name to reuse or create, or null to skip the class. For remote sourceUrl imports, create the dataset first, then pass its datasetId to ingest.

正文（已上传存档）：

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

正文（远程存档或 NDJSON）：

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

请求体（后续摄取，导入标签）：

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

类映射

首次摄取会自动从归档文件中创建类。在后续摄取时，归档文件中未包含在 classMapping 内的类，将首先回退到与现有数据集类进行不区分大小写的匹配。仅当类被显式映射为 null 或没有匹配的现有类时，才会跳过相应的标签。

响应：

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Link to this section数据集图像#

Link to this section列出图像#

GET /api/datasets/{datasetId}/images

查询参数：

参数	类型	描述
`split`	string	按拆分过滤：`train`、`val`、`test`
`offset`	int	分页偏移量（默认：0）
`limit`	int	每页项目数（默认：50，最大：5000）
`sort`	string	排序方式：`newest`、`oldest`、`name-asc`、`name-desc`、`height-asc`、`height-desc`、`width-asc`、`width-desc`、`size-asc`、`size-desc`、`labels-asc`、`labels-desc`（对于超过 10 万张图像的数据集，部分排序方式已禁用）
`hasLabel`	string	按标签状态过滤（`true` 或 `false`）
`hasError`	string	按错误状态过滤（`true` 或 `false`）
`search`	string	按文件名或图像哈希搜索
`classIds`	string	逗号分隔的类别 ID；返回包含任何指定类别的图像
`includeThumbnails`	string	包含带签名的缩略图 URL（默认：`true`）
`includeImageUrls`	string	包含带签名的完整图像 URL（默认：`false`）

Link to this section获取所选图像#

POST /api/datasets/{datasetId}/images

返回最多 1,000 个所提供图像 ID 的相同图像形状。它接受与列表操作相同的 URL 和标签查询控件。

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Link to this section获取带签名的图像 URL#

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

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

Link to this section删除图像#

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

Link to this section获取图像标签#

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

返回特定图像的标注和类别名称。

Link to this section更新图像标签#

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

请求体：

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

坐标格式

标签坐标使用 YOLO 0 到 1 之间的归一化值。边界框使用 [x_center, y_center, width, height]。分割标签使用 segments，这是一个多边形顶点的展平列表 [x1, y1, x2, y2, ...]。

Link to this section批量图像操作#

在数据集内移动拆分（train/val/test）之间的图像：

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

批量删除图像：

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

Link to this section项目 API#

将模型组织到项目中。每个模型仅属于一个项目。请参阅项目文档。

Link to this section列出项目#

GET /api/projects

查询参数：

参数	类型	描述
`username`	string	按用户名过滤
`limit`	int	每页项目数
`owner`	string	工作区所有者用户名

Link to this section获取项目#

GET /api/projects/{projectId}

Link to this section创建项目#

POST /api/projects

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

Link to this section更新项目#

PATCH /api/projects/{projectId}

Link to this section删除项目#

DELETE /api/projects/{projectId}

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

Link to this section克隆项目#

POST /api/projects/{projectId}/clone

将公共、自有或可编辑的工作区项目及其模型克隆到你的账户或工作区中。可选的 JSON 主体接受 name、slug、description、visibility、license 以及目标 owner 覆盖。

Link to this section项目图标#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

上传一个最大 5 MB 的 WebP 图标作为 multipart 表单字段 image，或移除当前图标。

Link to this sectionModels API#

管理已训练的 YOLO 模型——查看指标、下载权重、运行推理并导出为其他格式。请参阅 Models 文档。

Link to this section列出模型#

GET /api/models

查询参数：

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

Link to this section列出已完成的模型#

GET /api/models/completed

返回所有项目中最多 1,000 个可用于训练和部署的可用权重模型。为工作区传递 owner。

Link to this section获取模型#

GET /api/models/{modelId}

Link to this section创建模型#

POST /api/models

JSON 正文：

字段	类型	必填	描述
`projectId`	string	是	目标项目 ID
`slug`	string	否	URL 别名（小写字母数字/连字符）
`name`	string	否	显示名称（最多 100 个字符）
`description`	string	否	模型描述（最多 1000 个字符）
`task`	string	否	任务类型（detect、segment、semantic、pose、obb、classify）

模型文件上传

To attach .pt weights, request a signed upload URL with assetType: models and this model's ID as assetId, upload the file, then call POST /api/upload/complete with the returned sessionId.

Link to this section更新模型#

PATCH /api/models/{modelId}

Link to this section删除模型#

DELETE /api/models/{modelId}

Link to this section下载模型文件#

GET /api/models/{modelId}/files

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

Link to this section克隆模型#

POST /api/models/{modelId}/clone

将公共、自有或可编辑的工作区模型克隆到你的项目之一中。

请求体：

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

字段	类型	必填	描述
`targetProjectSlug`	string	是	目标项目别名
`modelName`	string	否	克隆模型的名称
`description`	string	否	模型描述
`owner`	string	否	团队用户名（用于工作区克隆）

Link to this section追踪下载#

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

追踪模型下载分析。

Link to this section运行推理#

POST /api/models/{modelId}/predict

公共模型无需身份验证即可进行预测。私有和共享模型需要具有父项目访问权限的 API key。

多部分表单：

字段	类型	描述
`file`	文件	图像或视频文件（例如 JPG、PNG、WebP、BMP、TIFF；MP4、MOV、AVI）
`source`	string	图像 URL 或 base64 编码的图像（`file` 的替代方案）
`conf`	float	置信度阈值，0.01–1（默认：0.25）
`iou`	float	IoU 阈值，0–0.95（默认：0.7）
`imgsz`	int	图像大小，32–1280 像素（默认：640）
`normalize`	布尔值	返回归一化坐标（默认：`false`）
`decimals`	int	坐标精度，0–10（默认：5）

提供 file 或 source。最大上传大小为 100 MB。

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

响应：

响应包含每个图像的 shape、speed、results 和可选的语义掩码数据，以及包含图像计数、函数计时、任务和服务版本的 metadata。永远不会返回内部模型路径。

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

Link to this sectionTraining API#

在云端 GPU（从 RTX 2000 Ada 到 B300 等 26 种 GPU 类型）上启动 YOLO 训练，并实时监控进度。请参阅 Cloud Training 文档。

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

Link to this section开始训练#

POST /api/training/start

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

GPU 类型

可用的 GPU 类型包括 rtx-4090、a100-80gb-pcie、a100-80gb-sxm、h100-sxm、rtx-pro-6000、b300 等。有关完整列表及定价，请参阅 Cloud Training。

Link to this section获取 GPU 可用性#

GET /api/training/gpu-availability

返回按 GPU 类型 ID 键控的当前 GPU 库存状态（High、Medium、Low 或 null）。公开，无需身份验证；缓存时间为 5 分钟。

Link to this section获取训练状态#

GET /api/models/{modelId}/training

返回当前训练作业的状态、指标、进度、计时、GPU 详细信息和错误。公共项目无需身份验证即可访问；私有和共享项目需要具有访问权限的 API key。

Link to this section取消训练#

DELETE /api/models/{modelId}/training

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

Link to this sectionDeployments API#

将模型部署到带有健康检查和监控功能的专用推理端点。新部署默认使用按需缩容 (scale-to-zero)，API 接受一个可选的 resources 对象。请参阅 Endpoints 文档。

各路由的 API 密钥支持情况

以下所有部署路由均接受 API-key 身份验证。对于高吞吐量推理，请直接使用你的 API key 调用部署自身的端点 URL（例如 https://predict-abc123.run.app/predict）。专用端点不受速率限制。

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Link to this section列出部署#

GET /api/deployments

查询参数：

参数	类型	描述
`modelId`	string	按模型过滤
`status`	string	按状态过滤
`limit`	int	最大结果数（默认：20，最大：100）
`owner`	string	工作区所有者用户名

Link to this section创建部署#

POST /api/deployments

请求体：

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

字段	类型	必填	描述
`modelId`	string	是	要部署的模型 ID
`name`	string	是	部署名称
`region`	string	是	部署区域
`resources`	对象	否	资源配置（`cpu`、`memoryGi`、`minInstances`、`maxInstances`）

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

默认资源

部署对话框目前提交的固定默认值为 cpu=1、memoryGi=2、minInstances=0 和 maxInstances=1。API 路由接受 resources 对象，但计划限制将 minInstances 上限设为 0，将 maxInstances 上限设为 1。

区域选择

选择一个靠近你用户的区域以获得最低延迟。平台 UI 会显示所有 42 个可用区域的延迟预估。

Link to this section获取部署#

GET /api/deployments/{deploymentId}

Link to this section删除部署#

DELETE /api/deployments/{deploymentId}

Link to this section启动部署#

POST /api/deployments/{deploymentId}/start

恢复已停止的部署。

Link to this section停止部署#

POST /api/deployments/{deploymentId}/stop

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

Link to this section健康检查#

GET /api/deployments/{deploymentId}/health

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

Link to this section在部署上运行推理#

POST /api/deployments/{deploymentId}/predict

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

多部分表单：

字段	类型	描述
`file`	文件	图像或视频文件
`source`	string	图像 URL 或 base64 编码的图像（`file` 的替代方案）
`conf`	float	置信度阈值，0.01–1（默认：0.25）
`iou`	float	IoU 阈值，0–0.95（默认：0.7）
`imgsz`	int	图像大小，32–1280 像素（默认：640）
`normalize`	布尔值	返回归一化坐标（默认：`false`）
`decimals`	int	坐标精度，0–10（默认：5）

提供 file 或 source。响应使用与模型预测相同的图像和元数据约定，且绝不会返回内部模型路径。

Link to this section获取指标#

GET /api/deployments/{deploymentId}/metrics

返回包含迷你图数据的请求计数、延迟和错误率指标。

查询参数：

参数	类型	描述
`range`	string	时间范围：`1h`、`6h`、`24h`（默认）、`7d`、`30d`
`sparkline`	string	设置为 `true` 以获取针对仪表板视图优化的迷你图数据

Link to this section获取日志#

GET /api/deployments/{deploymentId}/logs

查询参数：

参数	类型	描述
`severity`	string	以逗号分隔的过滤器：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`
`limit`	int	条目数量（默认：50，最大：200）
`pageToken`	string	来自前一个响应的分页令牌

Link to this section导出 API#

将模型转换为 ONNX、TensorRT、CoreML 和 LiteRT 等优化格式以进行边缘部署。请参阅 Deploy 文档。

Link to this section列出导出项#

GET /api/exports

查询参数：

参数	类型	描述
`modelId`	string	模型 ID（必填）
`status`	string	按状态过滤
`limit`	int	最大结果数（默认：20，最大：100）

Link to this section创建导出#

POST /api/exports

请求体：

字段	类型	必填	描述
`modelId`	string	是	源模型 ID
`format`	string	是	导出格式（见下表）
`gpuType`	string	条件项	当 `format` 为 `engine` 时必需；请使用受支持的 GPU 或 Jetson 目标
`args`	对象	否	导出参数（`imgsz`、`quantize`、`dynamic` 等）

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

支持的格式：

格式	值	用例
ONNX	`onnx`	跨平台推理
TorchScript	`torchscript`	PyTorch 部署
OpenVINO	`openvino`	Intel 硬件
TensorRT	`engine`	NVIDIA GPU 优化
CoreML	`coreml`	Apple 设备
TF SavedModel	`saved_model`	TensorFlow Serving
TF GraphDef	`pb`	TensorFlow frozen graph
PaddlePaddle	`paddle`	Baidu PaddlePaddle
NCNN	`ncnn`	移动神经网络
LiteRT	`litert`	移动端/边缘设备及浏览器
Edge TPU	`edgetpu`	Google Coral 设备
MNN	`mnn`	阿里巴巴移动推理
RKNN	`rknn`	Rockchip NPU
Qualcomm	`qnn`	Qualcomm Snapdragon NPU
IMX	`imx`	Sony IMX500 传感器
Axelera	`axelera`	Axelera AI 加速器
ExecuTorch	`executorch`	Meta ExecuTorch 运行时
DeepX	`deepx`	DeepX NPU 加速器

Link to this section获取导出状态#

GET /api/exports/{exportId}

Link to this section取消导出#

DELETE /api/exports/{exportId}

Link to this section跟踪导出下载#

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

Link to this section活动 API#

查看你账户近期操作的动态——训练运行、上传等。请参阅 Activity 文档。

各路由的 API 密钥支持情况

以下所有活动路由均接受 API-key 身份验证。

Link to this section列出活动#

GET /api/activity

查询参数：

参数	类型	描述
`limit`	int	页面大小（默认：20，最大：100）
`page`	int	页码（默认：1）
`archived`	布尔值	`true` 表示存档选项卡，`false` 表示收件箱
`search`	string	事件字段中的不区分大小写搜索
`start`	日期	包含此日期及之后的事件
`end`	日期	包含此日期及之前的事件
`export`	布尔值	将所有匹配的事件作为 JSON 返回
`owner`	string	工作区用户名

Link to this section标记事件为已读#

POST /api/activity/mark-seen

请求体：

{
    "all": true
}

或传入特定 ID：

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

传递可选的 owner 查询参数以标记工作区中的事件。

Link to this section存档事件#

POST /api/activity/archive

请求体：

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

或传入特定 ID：

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

传递可选的 owner 查询参数以归档或还原工作区事件。

Link to this section回收站 API#

查看并恢复已删除的项目。项目将在 30 天后被永久删除。请参阅 Trash 文档。

Link to this section列出回收站项目#

GET /api/trash

查询参数：

参数	类型	描述
`type`	string	筛选器：`all`，`project`，`dataset`，`model`
`page`	int	页码（默认：1）
`limit`	int	每页项目数（默认：50，最大：200）
`owner`	string	工作区所有者用户名

Link to this section恢复项目#

POST /api/trash

请求体：

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

Link to this section永久删除项目#

DELETE /api/trash

请求体：

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

不可逆

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

Link to this section清空回收站#

DELETE /api/trash/empty

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

身份验证

DELETE /api/trash/empty 接受 API-key 身份验证并永久删除所选账户或工作区垃圾箱中的所有项目。

Link to this section账单 API#

查看你的信用余额、计划使用情况和交易记录。请参阅账单文档。

货币单位

账单金额使用分（creditsCents），其中 100 = $1.00。

Link to this section获取余额#

GET /api/billing/balance

查询参数：

参数	类型	描述
`owner`	string	工作区所有者用户名

响应：

{
    "creditsCents": 2500,
    "plan": "free"
}

Link to this section获取使用情况摘要#

GET /api/billing/usage-summary

返回计划详情、限额和使用指标。

Link to this section获取交易记录#

GET /api/billing/transactions

返回交易历史（最近的优先）。

交易记录包含面向客户端的账本字段，例如金额、最终余额、日期、可选的模型上下文和收据 URL。内部备注、Stripe 支付/退款 ID 和幂等键不会被返回。

查询参数：

参数	类型	描述
`owner`	string	工作区所有者用户名

Link to this section存储 API#

按类别（数据集、模型、导出文件）查看你的存储使用明细，并查看你占用空间最大的项目。

API-key 访问

GET /api/storage 接受 API-key 身份验证。使用设置 > 个人资料页面查看相同的交互式细分。

Link to this section获取存储信息#

GET /api/storage

查询参数：

参数	类型	描述
`details`	布尔值	设为 `true` 以包含 `topItems`（最大的数据集、模型、导出项目）。
`owner`	string	工作区用户名。

响应：

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

Link to this section云存储集成#

连接并浏览只读的 GCS、S3 或 Azure Blob 存储集成：

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

所有四种操作都接受用于工作区的可选 owner 查询参数。对象浏览还接受所需的 target 以及可选的 prefix 和提供程序 cursor 查询参数。连接和发现请求主体使用交互式 OpenAPI 参考中的提供程序凭据模式；凭据永远不会被返回。

Link to this section上传 API#

使用签名 URL 直接上传文件到云存储，以实现快速可靠的传输。完成模型上传会附加其权重。完成数据集归档上传会记录会话；将该 sessionId 传递给 POST /api/datasets/ingest 以开始处理。请参阅数据文档。

Link to this section获取预签名上传 URL#

POST /api/upload/signed-url

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

请求体：

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

字段	类型	描述
`assetType`	string	资产类型：`models`、`datasets`、`images`、`videos`
`assetId`	string	目标资产的 ID
`filename`	string	原始文件名
`contentType`	string	MIME 类型
`totalBytes`	int	文件大小（字节）

响应：

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Link to this section完成上传#

POST /api/upload/complete

通知平台文件上传已完成。对于模型，这会附加已上传的权重。对于数据集归档，这会验证并记录上传会话；之后调用 POST /api/datasets/ingest 以开始数据集处理。

请求体：

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

Link to this section集成 API#

从第三方服务导入数据集。请参阅集成文档。

Link to this section预览 Roboflow 导入#

POST /api/integrations/roboflow/preview

将 Roboflow API key 解析为批量导入计划：工作区信息、将要新导入的项目、已导入版本的计数（已跳过）以及不支持的项目类型。Roboflow API key 在正文中传递且不会被持久化。

Link to this section从 Roboflow 导入#

POST /api/integrations/roboflow/import

将数据集提取任务加入队列，以将选定的 Roboflow 项目导入到你的工作区。需要存储空间，且每个数据集必须符合你计划的单次导入大小限制。

Link to this sectionAPI Keys API#

管理用于程序化访问的 API key。详见 API Keys documentation。

Link to this section列出 API keys#

GET /api/api-keys

经过 API-key 身份验证的客户端会收到密钥元数据，绝不会收到已解密的现有密钥值。新创建的密钥将由 POST /api/api-keys 返回一次。

传递可选的 owner 查询参数，以管理你拥有编辑权限的工作区的密钥。

Link to this section创建 API key#

POST /api/api-keys

请求体：

{
    "name": "training-server"
}

Link to this section删除 API key#

DELETE /api/api-keys

查询参数：

参数	类型	描述
`keyId`	string	要撤销的 API key ID
`owner`	string	可选的工作区用户名。

示例：

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

Link to this section团队与成员 API#

创建团队工作区、邀请成员并管理协作角色。详见 Teams documentation。

Link to this section列出团队#

GET /api/teams

Link to this section创建团队#

POST /api/teams/create

请求体：

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

Link to this section列出成员#

GET /api/members

返回当前工作区的成员。

Link to this section邀请成员#

POST /api/members

请求体：

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

成员角色

角色	权限
`viewer`	对工作区资源的只读访问权限
`editor`	创建、编辑和删除资源
`admin`	管理成员、账单和所有资源（仅限团队所有者分配）

团队 owner 是创建者，不能被邀请。所有者权限需通过 POST /api/members/transfer-ownership 单独转移。完整角色详情请查看 Teams。

Link to this section更新成员角色#

PATCH /api/members/{userId}

Link to this section移除成员#

DELETE /api/members/{userId}

Link to this section转移所有权#

POST /api/members/transfer-ownership

Link to this section探索 API#

搜索并浏览社区共享的公共数据集和项目。详见 Explore documentation。

Link to this section搜索公共内容#

GET /api/explore/search

查询参数：

参数	类型	描述
`q`	string	搜索查询
`type`	string	资源类型：`all`（默认）、`projects`、`datasets`
`sort`	string	排序顺序：`newest`（默认）、`stars`、`oldest`、`name-asc`、`name-desc`、`count-desc`、`count-asc`
`offset`	int	分页偏移量（默认：0）。每页返回 20 条结果。
`task`	string	可选：用于过滤数据集的逗号分隔 YOLO 任务类型（`detect`、`segment`、`semantic`、`classify`、`pose`、`obb`）
`author`	string	可选的所有者用户名筛选器。
`starred`	布尔值	设置为 `true` 以返回已通过身份验证的调用者加星标的内容；需要 API key。

Link to this section侧边栏数据#

GET /api/explore/sidebar

返回用于“探索”侧边栏的精选内容。

Link to this section用户与设置 API#

管理你的个人资料、API keys、存储使用情况和团队工作区。请参阅设置文档。

Link to this section账户摘要#

GET /api/account/summary

返回已通过身份验证的账户的计划、信用余额、资源计数和团队工作区。

Link to this section通过用户名获取用户#

GET /api/users

查询参数：

参数	类型	描述
`username`	string	要查找的用户名

Link to this section关注或取消关注用户#

PATCH /api/users

请求体：

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

Link to this section检查用户名可用性#

GET /api/username/check

查询参数：

参数	类型	描述
`username`	string	要检查的用户名
`suggest`	布尔值	可选：如果用户名已被占用，设为 `true` 以包含建议

Link to this section设置#

GET /api/settings
POST /api/settings

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

Link to this section工作区图标#

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

上传一个最大 5 MB 的 WebP 个人资料/工作区图标作为 multipart 表单字段 image，或将其移除。为团队工作区传递可选的 owner。

Link to this section错误代码#

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

Link to this sectionPython 集成#

为了更轻松地进行集成，请使用 Ultralytics Python 软件包，它能自动处理身份验证、上传和实时指标流传输。

Link to this section安装与设置#

pip install ultralytics

验证安装：

yolo check

软件包版本要求

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

Link to this section身份验证#

yolo settings api_key=YOUR_API_KEY

Link to this section使用平台数据集#

使用 ul:// URI 引用数据集：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

URI 格式：

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

Link to this section推送到平台#

将结果发送到平台项目：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

同步内容：

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

Link to this sectionAPI 示例#

从平台加载模型：

# 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, quantize=16)

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

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

验证：

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

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

Link to this section常见问题解答#

Link to this section如何对大量结果进行分页？#

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

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

Activity 和 Trash 端点也支持用于基于页码分页的 page 参数：

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

Explore Search 端点使用 offset 而不是 page，固定页面大小为 20：

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

Link to this section我可以不使用 SDK 调用 API 吗？#

上述记录的公共 REST 操作无需 Python SDK 即可使用。SDK 是一个便利的封装，增加了实时指标流和自动模型上传等功能。你可以在 platform.ultralytics.com/api/docs 以交互方式探索机器可读契约；仅限浏览器会话的账户流程保留在平台 UI 中。

Link to this section有 API 客户端库吗？#

目前，请使用 Ultralytics Python 软件包或直接发起 HTTP 请求。计划后续提供其他语言的官方客户端库。

Link to this section如何处理速率限制？#

使用来自 429 响应的 Retry-After 标头，等待相应的时间：

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

Link to this section如何查找我的模型或数据集 ID？#

当你通过 API 创建资源时，系统会返回资源 ID。你也可以在平台 URL 中找到它们：

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

使用列表端点按名称搜索或按项目进行过滤。

贡献者

GLglenn-jocher²⁷ MYmykolaxboiko² AMamanharshx¹ AMambitious-octopus¹ ONonuralpszr¹ LAlaodouya¹ RAraimbekovm¹ SEsergiuwaxmann¹ LALaughing-q¹

创建于 2026年1月14日更新于 42分钟前

Link to this sectionREST API 参考#

Link to this sectionAPI 概览#

Link to this section身份验证#

Link to this section获取 API Key#

Link to this section授权请求头#

Link to this section示例#

Link to this sectionBase URL#

Link to this section速率限制#

Link to this section每个 API Key 的限制#

Link to this section专用端点（无限）#

Link to this section响应格式#

Link to this section成功响应#

Link to this section错误响应#

Link to this section数据集 API#

Link to this section列出数据集#

Link to this section获取数据集#

Link to this section创建数据集#

Link to this section更新数据集#

Link to this section数据集图标#

Link to this section删除数据集#

Link to this section克隆数据集#

Link to this section导出数据集#

Link to this section创建数据集版本#

Link to this section更新版本描述#

Link to this section还原数据集版本#

Link to this section获取类别统计信息#

Link to this section管理类别#

Link to this section重新分配拆分#

Link to this section数据集嵌入#

Link to this section图像聚类#

Link to this section获取在该数据集上训练的模型#

Link to this section自动标注数据集#

Link to this section数据集摄入#

Link to this section数据集图像#

Link to this section列出图像#

Link to this section获取所选图像#

Link to this section获取带签名的图像 URL#

Link to this section删除图像#

Link to this section获取图像标签#

Link to this section更新图像标签#

Link to this section批量图像操作#

Link to this section项目 API#

Link to this section列出项目#

Link to this section获取项目#

Link to this section创建项目#

Link to this section更新项目#

Link to this section删除项目#

Link to this section克隆项目#

Link to this section项目图标#

Link to this sectionModels API#

Link to this section列出模型#

Link to this section列出已完成的模型#

Link to this section获取模型#

Link to this section创建模型#

Link to this section更新模型#

Link to this section删除模型#

Link to this section下载模型文件#

Link to this section克隆模型#

Link to this section追踪下载#

Link to this section运行推理#

Link to this sectionTraining API#

Link to this section开始训练#

Link to this section获取 GPU 可用性#

Link to this section获取训练状态#

Link to this section取消训练#

Link to this sectionDeployments API#

Link to this section列出部署#

Link to this section创建部署#

Link to this section获取部署#

Link to this section删除部署#

Link to this section启动部署#

Link to this section停止部署#

Link to this section健康检查#

Link to this section在部署上运行推理#

Link to this section获取指标#

Link to this section获取日志#

Link to this section导出 API#

Link to this section列出导出项#

Link to this section创建导出#

Link to this section获取导出状态#