REST 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 参考。

API 概览#

该 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

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

身份验证#

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

获取 API Key#

转到 Settings > API Keys
点击 Create Key
复制生成的密钥

详细说明请参见 API Keys。

授权请求头#

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

Authorization: Bearer YOUR_API_KEY

API Key 格式

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

示例#

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

Base URL#

所有 API 端点均使用：

https://platform.ultralytics.com/api

速率限制#

该 API 针对每个 API 密钥强制实施基于滑动窗口和 Upstash Redis 的限制。每个路由使用下方的对应类别。

当受到频率限制时，API 会返回带有限制重试元数据的 429：

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

每个 API Key 的限制#

速率限制根据所调用的端点自动应用。高负载操作有更严格的限制以防止滥用，而标准 CRUD 操作共享一个慷慨的默认值：

类别	限制	适用范围
默认	100 次请求/分钟	未分配至下方类别的路由
训练	10 次请求/分钟	开始云端训练
上传	10 次请求/分钟	已签名的上传 URL、上传完成以及数据集导入
预测	20 次请求/分钟	通过 Platform API 路由进行模型和部署推理
导出	20 次请求/分钟	模型导出路由以及数据集导出/版本路由
下载	30 次请求/分钟	模型文件下载
修改	10 次请求/分钟	团队创建、存储集成更改、API 密钥、成员、邀请以及部署启动/停止
账单	5 次请求/分钟	自动充值与订阅结账路由
水合	20 次请求/分钟	水合选定的数据集图像集
聚类	10 次请求/分钟	数据集图像聚类

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

专用端点（无限）#

Dedicated endpoints 在你直接调用端点 URL（例如 https://predict-abc123.run.app/predict）时不受平台 API 密钥速率限制的影响。吞吐量随后取决于部署的服务配置。

处理速率限制

当你收到 429 状态码时，请等待 Retry-After（或直到 X-RateLimit-Reset）再进行重试。有关指数退避的实现，请参阅速率限制常见问题解答。

响应格式#

成功响应#

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

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

错误响应#

{
    "error": "Dataset not found"
}

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

数据集 API#

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

列出数据集#

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

获取数据集#

GET /api/datasets/{datasetId}

返回数据集详细信息，包括类别名称、拆分计数和其他由 Platform 管理的属性。自定义元数据需从下方的元数据端点单独加载。

当 {datasetId} 是数据集 slug 而不是 ID 时，请传递 username。

创建数据集#

POST /api/datasets

请求体：

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

支持的任务

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

响应：

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

更新数据集#

PATCH /api/datasets/{datasetId}

请求体（部分更新）：

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

发送一个空的 metadata 对象（{}）以清除自定义元数据。序列化后的元数据对象限制为 500,000 个字符，且每个顶级键限制为 128 个字符。

获取数据集元数据#

GET /api/datasets/{datasetId}/metadata

返回自定义元数据对象以及一组精选的只读 Ultralytics 管理的字段/值对。普通数据集有效负载中刻意省略了自定义元数据。需要进行身份验证和数据集工作区访问权限。

数据集图标#

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

上传大小不超过 5 MB 的 WebP 图标作为 multipart 表单字段 image，或者删除当前图标。

删除数据集#

DELETE /api/datasets/{datasetId}

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

克隆数据集#

POST /api/datasets/{datasetId}/clone

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

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

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

导出数据集#

GET /api/datasets/{datasetId}/export

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

查询参数：

参数	类型	描述
`v`	integer	版本号（从 1 开始索引）。如果省略，则返回最新的可修改导出，并在数据集未更改时予以重用。

响应：

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

创建数据集版本#

POST /api/datasets/{datasetId}/export

为数据集创建一个新的编号版本快照。这需要编辑者（Editor）或更高权限。该版本会捕获当前的图像数量、类别数量、标注数量以及拆分分布，然后生成并存储不可变的 NDJSON 导出。

请求体：

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

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

响应：

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

更新版本描述#

PATCH /api/datasets/{datasetId}/export

更新现有版本的描述。这需要编辑者（Editor）或更高权限。

请求体：

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

响应：

{
    "ok": true
}

还原数据集版本#

POST /api/datasets/{datasetId}/restore

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

{
    "version": 2
}

获取类别统计信息#

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
}

管理类别#

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

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

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

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

删除类别：

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

{
    "classIds": [2, 4]
}

重新分配拆分#

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

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

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

数据集嵌入#

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

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

图像聚类#

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

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

获取在该数据集上训练的模型#

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`	string	是	要标注图像的哈希值
`modelId`	string	否	用于推理的模型，作为 `ul://` URI（例如 `ul://username/project/model`）。如果省略，则使用数据集的任务特定默认模型。
`confidence`	float	否	置信度阈值（默认：0.25）
`iou`	float	否	IoU 阈值（默认：0.7）

数据集摄入#

POST /api/datasets/ingest

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

请求主体需要 datasetId 以及 sessionId（已上传归档的上传会话）或 sourceUrl（远程 ZIP、TAR、TAR.GZ、TGZ 或 NDJSON URL）中的且仅能有一个。添加可选的 targetSplit（train、val 或 test）以覆盖归档的分割结构。若要附加自定义元数据，请使用 imageMetadata，以每张图片的准确归档相对路径或 NDJSON file 值为键。

对于上传的归档文件，上传会话已通过传递给 POST /api/upload/signed-url 的 assetId 绑定到数据集；数据导入会验证 assetId 是否与请求体 datasetId 匹配。可选的 classMapping 条目将每个传入的类别名称映射到现有的基于零的类别索引、要复用或创建的类别名称，或 null 以跳过该类别。对于远程 sourceUrl 导入，请先创建数据集，然后将其 datasetId 传递给数据导入。

正文（已上传存档）：

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

主体（带元数据的单张或多张图片）：

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

本地图片使用现有的归档上传流程，无论归档包含一张还是多张图片。键必须与归档内的规范化路径（包含文件夹）相匹配。对于 NDJSON 导入，每个图片记录可以改为包含其自己的 metadata 对象。记录本地的 metadata 优先于匹配的 imageMetadata 条目。

元数据是 JSON 格式并支持嵌套值。归档路径限制在 1,024 个字符以内，顶层元数据键限制在 128 个字符以内，每个元数据对象限制在 500,000 个序列化字符以内。完整的 imageMetadata 映射，或 NDJSON 导入中组合的有效元数据，同样限制在 500,000 个序列化字符以内。这些限制包含在交互式 OpenAPI schema 中。

使用 Python 上传带有元数据的一张图片

相同的代码可以处理一组图片：向 ZIP 中添加更多文件，并在 imageMetadata 中添加匹配的条目。

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

正文（远程存档或 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

数据集图像#

列出图像#

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	对文件名和自定义元数据键、标量值以及数组条目进行子字符串匹配（不匹配子对象中嵌套的值）；32 字符的十六进制字符串表示精确的图像哈希查找
`classIds`	string	逗号分隔的类别 ID；返回包含任何指定类别的图像
`includeThumbnails`	string	包含签名的缩略图 URL（默认值：`true`）
`includeImageUrls`	string	包含签名的完整图像 URL（默认值：`false`）

获取所选图像#

POST /api/datasets/{datasetId}/images

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

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

获取带签名的图像 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] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

坐标格式

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

批量图像操作#

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

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

批量删除图像：

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

项目 API#

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

列出项目#

GET /api/projects

查询参数：

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

获取项目#

GET /api/projects/{projectId}

创建项目#

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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

更新项目#

PATCH /api/projects/{projectId}

请求体（部分更新）：

{
    "metadata": { "department": "research", "program": "inspection" }
}

发送一个空的 metadata 对象（{}）以将其清除。项目元数据使用与数据集元数据相同的 128 字符顶级键和 500,000 字符序列化对象限制。

获取项目元数据#

GET /api/projects/{projectId}/metadata

返回自定义元数据对象和只读 Ultralytics 管理的字段/值对。需要进行身份验证和项目工作区访问权限。

删除项目#

DELETE /api/projects/{projectId}

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

克隆项目#

POST /api/projects/{projectId}/clone

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

项目图标#

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

上传大小不超过 5 MB 的 WebP 图标作为 multipart 表单字段 image，或者删除当前图标。

Models API#

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

列出模型#

GET /api/models

查询参数：

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

列出已完成的模型#

GET /api/models/completed

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

获取模型#

GET /api/models/{modelId}

创建模型#

POST /api/models

JSON 正文：

字段	类型	必填	描述
`projectId`	string	是	目标项目 ID
`slug`	string	否	URL 别名（小写字母数字/连字符）
`name`	string	否	显示名称（最多 100 个字符）
`description`	string	否	模型描述（最多 1000 个字符）
`metadata`	对象	否	自定义 JSON 元数据
`task`	string	否	任务类型 (detect, segment, semantic, depth, pose, obb, classify)

模型文件上传

要附加 .pt 权重，请使用 assetType: models 和此模型的 ID 作为 assetId 请求一个签名的上传 URL，上传文件，然后调用带有返回的 sessionId 的 POST /api/upload/complete。

更新模型#

PATCH /api/models/{modelId}

请求体（部分更新）：

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

发送一个空的 metadata 对象（{}）以将其清除。模型自定义元数据与训练拥有的模型信息、环境详情和训练参数是分开的，并使用与数据集元数据相同的序列化对象和顶级键限制。

获取模型元数据#

GET /api/models/{modelId}/metadata

返回自定义元数据对象和只读 Ultralytics 管理的字段/值对。需要进行身份验证和模型工作区访问权限。

删除模型#

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`	string	是	目标项目别名
`modelName`	string	否	克隆模型的名称
`description`	string	否	模型描述
`owner`	string	否	团队用户名（用于工作区克隆）

追踪下载#

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

追踪模型下载分析。

运行推理#

POST /api/models/{modelId}/predict

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

多部分表单：

参数	类型	默认值	范围	描述
`file`	文件	-	-	图像或视频文件（除非设置了 `source`，否则为必填）
`conf`	float	0.25	0.01 – 1.0	最低置信度阈值
`iou`	float	0.7	0.0 – 0.95	NMS IoU 阈值
`imgsz`	int	640	32 – 1280	输入图像尺寸（以像素为单位）
`normalize`	布尔值	false	-	将边界框坐标返回为 0 – 1
`decimals`	int	5	0 – 10	坐标值的小数精度
`source`	string	-	-	图像 URL 或 base64 字符串（`file` 的替代方案）

提供 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 以及可选的稠密像素映射数据（语义类映射，或深度映射，其中 depth = pixel × max / divisor — 默认 8 位映射的除数为 255，使用 bits=12|16 时为 65535），外加包含图像计数、函数耗时、任务和服务版本的 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
    }
}

Training API#

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

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

开始训练#

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 等。完整列表及定价请参见云端训练。

获取 GPU 可用性#

GET /api/training/gpu-availability

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

获取训练状态#

GET /api/models/{modelId}/training

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

取消训练#

DELETE /api/models/{modelId}/training

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

Deployments API#

将模型部署到带有健康检查和监控功能的专用推理端点。新部署默认使用缩减至零（scale-to-zero），且 API 接受可选的 resources 对象。请参阅端点文档。

各路由的 API 密钥支持情况

以下所有部署路由都接受 API 密钥身份验证。对于高吞吐量推理，请直接使用你的 API 密钥调用部署自身的端点 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

列出部署#

GET /api/deployments

查询参数：

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

创建部署#

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 个可用区域的延迟预估。

获取部署#

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`	文件	-	-	图像或视频文件（除非设置了 `source`，否则为必填）
`conf`	float	0.25	0.01 – 1.0	最低置信度阈值
`iou`	float	0.7	0.0 – 0.95	NMS IoU 阈值
`imgsz`	int	640	32 – 1280	输入图像尺寸（以像素为单位）
`normalize`	布尔值	false	-	将边界框坐标返回为 0 – 1
`decimals`	int	5	0 – 10	坐标值的小数精度
`source`	string	-	-	图像 URL 或 base64 字符串（`file` 的替代方案）

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

获取指标#

GET /api/deployments/{deploymentId}/metrics

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

查询参数：

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

获取日志#

GET /api/deployments/{deploymentId}/logs

查询参数：

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

导出 API#

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

列出导出项#

GET /api/exports

查询参数：

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

创建导出#

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

支持的格式：

使用下方共享导出表中的 format 参数。PyTorch 是源格式，并非 API 导出目标。

格式	`format` 参数	模型	元数据	参数
PyTorch	-	`yolo26n.pt`	✅	-
TorchScript	`torchscript`	`yolo26n.torchscript`	✅	`imgsz`, `quantize`, `dynamic`, `nms`, `batch`, `device`
ONNX	`onnx`	`yolo26n.onnx`	✅	`imgsz`, `quantize`, `dynamic`, `simplify`, `opset`, `nms`, `batch`, `data`, `fraction`, `device`
OpenVINO	`openvino`	`yolo26n_openvino_model/`	✅	`imgsz`, `quantize`, `dynamic`, `nms`, `batch`, `data`, `fraction`, `device`
TensorRT	`engine`	`yolo26n.engine`	✅	`imgsz`, `quantize`, `dynamic`, `simplify`, `opset`, `workspace`, `nms`, `batch`, `data`, `fraction`, `device`
CoreML	`coreml`	`yolo26n.mlpackage`	✅	`imgsz`, `dynamic`, `quantize`, `nms`, `batch`, `device`
TF SavedModel	`saved_model`	`yolo26n_saved_model/`	✅	`imgsz`, `keras`, `quantize`, `opset`, `nms`, `batch`, `data`, `fraction`, `device`
TF GraphDef	`pb`	`yolo26n.pb`	❌	`imgsz`, `opset`, `batch`, `device`
TF Edge TPU	`edgetpu`	`yolo26n_edgetpu.tflite`	✅	`imgsz`, `quantize`, `opset`, `data`, `fraction`, `device`
PaddlePaddle	`paddle`	`yolo26n_paddle_model/`	✅	`imgsz`, `batch`, `device`
MNN	`mnn`	`yolo26n.mnn`	✅	`imgsz`, `batch`, `dynamic`, `quantize`, `simplify`, `opset`, `nms`, `device`
NCNN	`ncnn`	`yolo26n_ncnn_model/`	✅	`imgsz`, `quantize`, `batch`, `device`
IMX500	`imx`	`yolo26n_imx_model/`	✅	`imgsz`, `quantize`, `data`, `fraction`, `nms`, `device`
RKNN	`rknn`	`yolo26n_rknn_model/`	✅	`imgsz`, `batch`, `name`, `quantize`, `simplify`, `opset`, `data`, `fraction`, `device`
ExecuTorch	`executorch`	`yolo26n_executorch_model/`	✅	`imgsz`, `batch`, `device`
Axelera	`axelera`	`yolo26n_axelera_model/`	✅	`imgsz`, `batch`, `quantize`, `data`, `fraction`, `device`
DEEPX	`deepx`	`yolo26n_deepx_model/`	✅	`imgsz`, `quantize`, `simplify`, `opset`, `data`, `optimize`, `device`
Qualcomm QNN	`qnn`	`yolo26n_qnn.onnx`	✅	`imgsz`, `batch`, `name`, `quantize`, `simplify`, `opset`, `data`, `fraction`, `device`
LiteRT	`litert`	`yolo26n.tflite`	✅	`imgsz`, `quantize`, `batch`, `data`, `fraction`, `device`
Hailo	`hailo`	`yolo26n_hailo_model/`	✅	`imgsz`, `name`, `quantize`, `data`, `fraction`, `simplify`, `conf`, `iou`
Huawei Ascend	`ascend`	`yolo26n_ascend_model/`	✅	`imgsz`, `batch`, `name`, `quantize`, `opset`, `simplify`, `nms`

获取导出状态#

GET /api/exports/{exportId}

取消导出#

DELETE /api/exports/{exportId}

跟踪导出下载#

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

活动 API#

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

各路由的 API 密钥支持情况

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

列出活动#

GET /api/activity

查询参数：

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

标记事件为已读#

POST /api/activity/mark-seen

请求体：

{
    "all": true
}

或传入特定 ID：

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

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

存档事件#

POST /api/activity/archive

请求体：

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

或传入特定 ID：

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

传递可选的 owner 查询参数以存档或恢复工作区事件。

回收站 API#

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

列出回收站项目#

GET /api/trash

查询参数：

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

恢复项目#

POST /api/trash

请求体：

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

永久删除项目#

DELETE /api/trash

请求体：

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

不可逆

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

清空回收站#

DELETE /api/trash/empty

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

身份验证

DELETE /api/trash/empty 接受 API 密钥身份验证，并永久删除所选账户或工作区回收站中的所有项目。

账单 API#

检查你的信用余额、套餐使用情况和交易历史。请参阅账单文档。

余额和交易端点接受一个可选的 owner 查询参数，用于指定工作区所有者的用户名。

货币单位

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

获取余额#

GET /api/billing/balance

响应：

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

获取使用情况摘要#

GET /api/billing/usage-summary

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

获取交易记录#

GET /api/billing/transactions

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

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

存储 API#

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

API-key 访问

GET /api/storage 接受 API 密钥身份验证。请使用设置 > 个人资料页面获取相同的交互式明细。

获取存储信息#

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

云存储集成#

连接并浏览只读的 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 参考中的提供商凭据架构；绝不会返回凭据。

上传 API#

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

获取预签名上传 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"
}

完成上传#

POST /api/upload/complete

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

请求体：

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

集成 API#

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

预览 Roboflow 导入#

POST /api/integrations/roboflow/preview

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

从 Roboflow 导入#

POST /api/integrations/roboflow/import

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

API Keys API#

管理用于编程访问的 API 密钥。请参阅API 密钥文档。

列出 API keys#

GET /api/api-keys

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

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

创建 API key#

POST /api/api-keys

请求体：

{
    "name": "training-server"
}

删除 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"

团队与成员 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`	管理成员、账单和所有资源（仅限团队所有者分配）

团队 owner 是创建者，不能被邀请。所有者身份通过 POST /api/members/transfer-ownership 单独转移。有关完整的角色详情，请参阅团队。

更新成员角色#

PATCH /api/members/{userId}

移除成员#

DELETE /api/members/{userId}

转移所有权#

POST /api/members/transfer-ownership

探索 API#

搜索和浏览社区共享的公共数据集和项目。请参阅探索文档。

搜索公共内容#

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

侧边栏数据#

GET /api/explore/sidebar

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

用户与设置 API#

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

账户摘要#

GET /api/account/summary

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

通过用户名获取用户#

GET /api/users

查询参数：

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

关注或取消关注用户#

PATCH /api/users

请求体：

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

检查用户名可用性#

GET /api/username/check

查询参数：

参数	类型	描述
`username`	string	要检查的用户名
`suggest`	布尔值	可选：`true`，用于在名称已被占用时包含建议

设置#

GET /api/settings
POST /api/settings

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

工作区图标#

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

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

Python 集成#

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

安装与设置#

pip install "ultralytics>=8.4.104"

验证安装：

yolo check

身份验证#

yolo login YOUR_API_KEY

使用平台数据集#

使用 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`	官方模型

推送到平台#

将结果发送到平台项目：

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

同步内容：

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

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

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

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

验证：

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

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

常见问题解答#

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

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

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

活动和回收站端点还支持用于基于页面的分页的 page 参数：

curl -H "Authorization: Bearer YOUR_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 即可使用。SDK 是一个便捷包装器，添加了实时指标流式传输和自动模型上传等功能。你可以在 platform.ultralytics.com/api/docs 以交互方式探索机器可读的契约；仅限浏览器会话的账户流程保留在 Platform UI 中。

有 API 客户端库吗？#

使用 Ultralytics Python 软件包或从任何语言发起直接 HTTP 请求。

如何处理速率限制？#

使用来自 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 RuntimeError("Rate limit exceeded")

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

资源 ID 由创建、列表和获取 API 响应返回。Platform 页面 URL 使用人类可读的别名（slug），而非数据库 ID：

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

使用列表端点查找模型、数据集、项目、部署或其他资源的相应 _id。

贡献者

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

创建于 2026年1月14日更新于昨天