YOLO Vision 2026：

REST API 参考#

Ultralytics Platform 提供了一个 REST API，用于以编程方式访问数据集、图像、项目、模型、训练、导出和部署。

Ultralytics Platform 交互式 API 文档

快速入门
# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

下面每个端点都列出了其来自 ultralytics-platform SDK 的 client.<resource>.<method>(...) 调用，该 SDK 是从与此参考相同的契约生成的。

交互式 API 参考

本页面是 API 的导览。生成的、始终最新的参考文档位于 platform.ultralytics.com/api/docs，驱动它的机器可读 OpenAPI 3.2 文档发布在 platform.ultralytics.com/openapi.json。这两者均直接从服务端契约生成，因此当本页面与架构不一致时，它们具有权威性。

API 概览#

API 围绕核心 Platform 资源组织：

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
资源描述关键操作
Datasets标注图像集CRUD、摄取、版本、类别、拆分、克隆
Images单张图像和标签读取、标注、移动拆分、删除、自动标注
Projects模型工作空间CRUD、克隆
模型已训练的检查点CRUD、预测、下载、克隆、训练状态
Training云端 GPU 训练任务GPU 可用性、启动、进度、取消
Exports格式转换任务创建、列表、状态、取消
Deployments专用推理端点创建、启动/停止/替换、预测、指标、日志
Trash软删除的资源列表、恢复、永久删除
Storage云存储集成连接、发现、浏览、断开连接
Account计划、点数、存储、个人资料账户摘要、API 密钥、存储使用量、用户查找
Billing计划使用情况和账单使用摘要、交易
Explore公开内容搜索搜索项目和数据集

身份验证#

大多数端点都需要 API 密钥。公开公开内容的端点（例如读取公共数据集、项目或模型，列出公共数据集图像，在公共模型上运行推理，或者搜索 Explore）也接受匿名请求，并在提供密钥时返回更多内容。

获取 API 密钥#

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

详细说明请参见 API Keys。

授权请求头#

将你的 API 密钥作为 bearer 令牌包含在内：

Authorization: Bearer YOUR_API_KEY
API Key 格式

API 密钥是由字面量前缀 ul_ 后面跟 40 个十六进制字符组成，总共 43 个字符（例如 ul_a1b2c3d4e5f6789012345678901234567890abcd）。缺少标头、密钥格式错误或密钥已被撤销的请求将返回 401。请妥善保管你的密钥 -- 切勿将其提交到版本控制系统或公开分享。

示例#

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

Base URL#

所有 API 端点均使用：

https://platform.ultralytics.com/api

资源路径#

资源的寻址使用的是 Platform URL 中显示的人类可读名称，而不是数据库 ID：

资源路径示例
数据集/api/datasets/{owner}/{dataset}/api/datasets/acme-vision/warehouse
项目/api/projects/{owner}/{project}/api/projects/acme-vision/inspection
模型/api/models/{owner}/{project}/{model}/api/models/acme-vision/inspection/v3
部署/api/deployments/{owner}/{deployment}/api/deployments/acme-vision/edge-1
图像/api/images/{imageId}/api/images/65f1c0a2b3d4e5f601234567
  • {owner} 是个人用户名或团队工作空间句柄：4-32 个字符，小写字母数字，段之间带有单个连字符。
  • {dataset}、{project}、{model} 和 {deployment} 遵循相同的小写连字符模式，最多 128 个字符。
  • {imageId} 和 {exportId} 是 API 返回的 24 个字符的十六进制 ID。
  • 通过 PATCH 重命名资源会同时更改显示的 name 和 URL 名称，且响应会返回当前的 URL 名称，以便你继续对其进行追踪。
工作空间选择

这里没有 owner 查询参数。工作空间范围的路径在路径中带有所有者，而账户范围的端点（/api/account/summary、/api/api-keys、/api/storage、/api/billing/*、/api/trash、/api/integrations/buckets）对发出 API 密钥的工作空间进行操作。若要对团队工作空间进行操作，请使用在该工作空间中创建的 API 密钥。

速率限制#

API 针对每个 API 密钥强制实施滑动窗口限制。每个路由都属于一个类别，并且每个类别都有一个独立的计数器，因此 20 个预测请求不会消耗你的默认额度。

类别限制适用范围
默认100 次请求/分钟未在下方列出的每个路由
训练10 次请求/分钟POST /api/training/start
上传10 次请求/分钟已签名的上传 URL、上传完成以及数据集导入
预测20 次请求/分钟通过 Platform API 路由进行模型和部署推理
导出20 次请求/分钟模型导出路由以及数据集导出/版本路由
下载30 次请求/分钟模型文件下载
修改10 次请求/分钟列出 API 密钥、连接或发现云存储以及部署 PATCH 操作
水合20 次请求/分钟POST /api/datasets/{owner}/{dataset}/images（获取选定的一组图像）
聚类10 次请求/分钟GET /api/datasets/{owner}/{dataset}/images/clustering

仅限浏览器的 Platform 路由（例如账单结账和团队管理）拥有其自身的限制，这些限制不适用于 API 密钥流量。

当受到限流时，API 会返回包含标头和 JSON 主体的 429：

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z
{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

专用端点（无限）#

当你直接调用部署自身的 serviceUrl（例如 https://predict-abc123.run.app/predict）时，专用端点不受 Platform API 密钥速率限制。吞吐量随后取决于已部署的服务配置。

处理速率限制

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

响应格式#

成功响应#

响应是带有资源特定字段的 JSON 对象。没有通用的信封：列表端点会返回带有计数的命名集合，而修改操作会返回更改后的标识符。

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

承载数据的响应还包括 region（us、eu 或 ap），即该工作空间的存储区域。

错误响应#

每个错误响应都是一个带有 error 消息的 JSON 对象：

{
    "error": "Dataset not found"
}
HTTP 状态含义
200成功
201已创建
202已接受，工作正在异步继续
400路径、查询或请求主体无效
401缺少或无效的身份验证
402点数不足（训练）
403权限、计划或配额不足
404资源未找到
409与当前状态冲突（名称重复、任务正在进行中）
413预测输入太大
422模型类别与数据集不匹配（自动标注）
429超出速率限制
500服务器错误
502上游提供商或服务调用失败
503依赖服务暂时不可用

分页#

分页样式取决于集合：

样式端点参数量
仅限限制数据集、项目、模型、导出、部署列表limit
偏移量和限制数据集图像、图像聚类、Explore 搜索offset、limit，外加响应中的 hasMore
游标数据集图像（大型数据集）cursor、includeTotal，外加 nextCursor
页码回收站page、limit，外加 totalPages
不透明的页面令牌部署日志pageToken，外加 nextPageToken

数据集 API#

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

列出数据集#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

返回所有者的公共数据集，当你的密钥可以查看该工作空间时还返回私有数据集。

查询参数：

参数类型描述
limitint要返回的最大数据集数（默认：1000，最大：1000）
includeSamples布尔值包含示例图像预览（默认：true）
includeImageUrls布尔值包含全尺寸示例图像回退 URL（默认：false）
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets/acme-vision?limit=10&includeSamples=false"

响应：

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

获取数据集#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

在 dataset 键下返回完整的数据集对象，包括 classNames、splits、versions、source 以及用户定义的 metadata 对象。

创建数据集#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

请求体：

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}
字段类型必填描述
datasetstring是Platform URL 中使用的服务名称（小写，带连字符，最多 128 个字符）
namestring是显示名称（最多 100 个字符）
descriptionstring否描述（最多 1000 个字符）
taskstring否任务类型（默认：detect）
classNamesarray否按索引顺序排列的类别名称（最多 25,000 个）
formatstring否标注格式：yolo（默认）、coco、raw、ndjson
visibilitystring否public 或 private
tagsarray否最多 50 个标签，每个标签 50 个字符
licensestring否数据集许可证标识符
metadata对象否自定义 JSON 元数据
ownerstring否团队工作空间句柄；默认为你的个人工作空间
支持的任务

创建或更新数据集时的有效 task 值：detect、segment、semantic、depth、classify、pose 和 obb。深度数据集没有类别。

响应（201）：

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

更新数据集#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

请求体（部分更新）：

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

接受的字段：name、description、visibility、metadata、tags、classNames、classColors、format、task、license、iconColor、iconLetter 和 starred。发送空的 metadata 对象（{}）以清除自定义元数据。元数据键限制为 128 个字符，序列化对象限制为 500,000 个字符。

响应：

{
    "success": true,
    "dataset": "warehouse-safety"
}

重命名会更改 URL 名称，因此请对后续请求使用返回的 dataset 值。

删除数据集#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

将数据集移动到回收站，在那里可以恢复 30 天。

克隆数据集#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

将可访问的数据集连同其图像和标签一起复制到你的个人工作空间或团队工作空间中。

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

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

响应（201）： id、owner、dataset、name、imageCount、classCount 和 region。由连接的存储源支持的数据集会返回 409，因为它们的文并未被复制。

下载数据集导出#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

返回已签名的 NDJSON 下载 URL。省略 v 以导出数据集当前状态，如果自生成以来没有任何更改，则重用缓存的导出。

查询参数：

参数类型描述
vinteger保存的版本号（从 1 开始索引）。当前数据集可省略。

响应：

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

请求特定版本会返回 downloadUrl 和 version，而不是 cached。

创建数据集版本#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

创建数据集的不可变编号快照并存储其 NDJSON 导出。需要编辑者权限。

正文（可选）：

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

响应：

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

如果自上一版本以来数据集未发生更改且返回了该快照，则 reused 为 true。

更新版本描述#

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

请求体：

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

响应： {"ok": true}

还原数据集版本#

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

从保存的版本重建图像、标注和类别，而不复制图像字节。

请求体：

{
    "version": 2
}

响应： {"version": 2, "imageCount": 1000}

获取数据集统计信息#

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

返回每个类别的标注计数、图像和标注直方图以及热力图。大型数据集会被采样，在这种情况下，sampleSize 会报告贡献了多少张图像。

响应（缩略）：

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

管理类别#

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

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

删除类别（其标注将被删除，且其余类别 ID 会向下移动）：

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

两个操作都会返回 success、更新后的 classNames 和 classColors，以及更改内容摘要（mergedClassIds 和 targetClassId，或者 deletedClassIds 和 deletedAnnotations）。

类别 ID 是位置相关的

由于合并或删除后剩余的 ID 会发生移动，因此这些操作不是幂等的。在执行另一个类别操作之前，请重新获取数据集以获得当前的类别索引。

重新分配拆分#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

随机重新分配各个拆分间的图像。这三个百分比的总和必须为 100。

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

响应： success、生成的 splits 计数以及 modified（移动的图像数量）。

数据集嵌入#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK： client.datasets.embeddings(owner, dataset)、client.datasets.create_embeddings(owner, dataset)、client.datasets.delete_embeddings(owner, dataset)

GET 返回分析摘要（analyzedAt、embeddingsCount、latestImageAt、activeJob）。POST 将嵌入分析加入队列并返回带有 jobId 的 202。DELETE 取消活动任务并返回已取消的任务 ID 或 null。

图像聚类#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

返回来自已完成分析的 UMAP 2D 布局，使用 offset 和 limit（默认且最大 50,000）进行分页。每个条目都有 id、umapX、umapY、split、classIds、width、height、bytes、labelCount 和 missing。

列出在数据集上训练的模型#

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

响应：

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

列出数据集图像#

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

查询参数：

参数类型描述
limitint返回的最大图像数（默认：50，最大：5000）
offsetint要跳过的图像数（默认：0）
cursorstring上一页的最后一个图像 ID，用于游标分页
includeTotal布尔值包含匹配的总计数（默认：true）
splitstring按拆分过滤：train、val、test
hasLabel布尔值按标注状态筛选
hasError布尔值按处理错误状态筛选
classIdsstring逗号分隔的类别 ID；返回包含其中任意一个类别的图像
searchstring对文件名和自定义元数据进行子字符串匹配（最多 200 个字符）
sortstringnewest（默认）、oldest、name-asc、name-desc、height-asc、height-desc、width-asc、width-desc、size-asc、size-desc、labels-asc、labels-desc
includeThumbnails布尔值包含签名的缩略图 URL（默认值：true）
includeImageUrls布尔值包含带签名的完整尺寸图像 URL（默认：false）
includeLabels布尔值包含上限预览标注（默认：false）

响应：

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

获取所选图像#

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

为最多 1,000 个提供的图像 ID 返回相同的图像形状，并接受与列表操作相同的筛选器和 URL 查询参数。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

提取数据集数据#

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

将已完成的上传、远程存档或连接的存储源处理到现有数据集中。仅提供一个源：

字段类型描述
sessionIdstring来自 POST /api/upload/signed-url 的上传会话，已完成
sourceUrlstringZIP、TAR、TAR.GZ、TGZ 或 NDJSON 文件的公共 HTTP 或 HTTPS URL（最多 4096 个字符）
reference对象连接的源：云存储（provider: "cloud"、integrationId、target、prefix）或本地部署（provider: "local"、keyId、root、prefix）
targetSplitstringtrain、val 或 test；覆盖存档的拆分结构
conflictPolicystring用于文件名或内容冲突的 skip、keep_both 或 replace
classMapping对象将传入的类别名称映射到类别索引、现有或新的类别名称，或使用 null 跳过
imageMetadata对象通过每个图像的存档相对路径或 NDJSON file 值进行键控的自定义元数据

上传会话通过传递给 POST /api/upload/signed-url 的 assetId 绑定到数据集，并且提取操作会拒绝属于不同数据集的会话。

正文（已上传存档）：

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

正文（远程存档或 NDJSON）：

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

正文（在稍后的提取中导入标签）：

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

正文（附加每张图像的元数据）：

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

元数据键必须与存档内的规范化路径匹配，包括文件夹。对于 NDJSON 导入，每个记录都可以携带自己的 metadata 对象，该对象优先于匹配的 imageMetadata 条目。存档路径限制为 1,024 个字符，顶级元数据键限制为 128 个字符，每个元数据对象以及整个 imageMetadata 映射限制为 500,000 个序列化字符。

类映射

第一次提取会自动从存档创建类别。在后续提取中，从 classMapping 中省略的存档类别将回退到对现有数据集类别进行不区分大小写的匹配。仅对显式映射到 null 或没有匹配现有类别的类别跳过标签。

响应（201）：

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}
graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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
使用 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"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

图像 API#

通过 24 个字符的图像 ID 检查、标注、移动和删除数据集图像。请参阅 标注文档。

获取图像#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

返回 metadata（自定义、用户定义）、properties（文件名、哈希、尺寸、拆分、计数、时间戳）、labels 以及数据集的 classNames。

更新图像#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

替换标注或自定义元数据——发送两种形态中的一种，而不是两者。

正文（标注）：

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

正文（元数据）：

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}
坐标格式

标签坐标使用介于 0 和 1 之间的 YOLO 规范化值。边界框使用 [x_center, y_center, width, height]。分割标签使用 segments（多边形顶点 [x1, y1, x2, y2, ...] 的扁平化列表）。姿态标签使用一种一致的扁平形态的 keypoints：成对的 [x1, y1, x2, y2, ...] 或三元的 [x1, y1, v1, x2, y2, v2, ...]，其中可见性惯例上使用 0、1 或 2。定向框使用 obb 角。保存的坐标四舍五入到小数点后 5 位，并且一张图像最多接受 10,000 个标注。

删除图像#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

永久删除一张图像及其标注。

自动标注图像#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

在图像上运行 YOLO 推理并返回预测的标注。它不会保存它们——当你对结果满意时，请使用 PATCH /api/images/{imageId} 将结果写回。

字段类型必填描述
modelIdstring是完全限定的模型 URI，ul://{owner}/{project}/{model}
confidencefloat否置信度阈值，0.01 – 1.0（默认：0.25）
ioufloat否非极大值抑制的 IoU 阈值，0.0 – 0.95（默认：0.7）

响应： success、predictions（标注对象）、modelUsed 和 inferenceTime。类别与数据集不匹配的模型会返回 422。

批量移动图像#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

将最多 1,000 张图像从一个数据集移动到另一个不同的拆分中。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

文件名或内容冲突会返回 409，直到你选择全篮子 conflictPolicy 的 skip、keep_both 或 replace。响应会报告 modifiedCount、skippedCount 和 targetSplit。

批量删除图像#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

从单个数据集删除最多 1,000 张图像，并返回 deletedCount 和 deletedImageIds。

获取带签名的图像 URL#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

为一个数据集中的最多 100 个图像 ID 返回带签名的临时 URL。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

响应： urls 和 thumbnails，两者均以图像 ID 为键。

项目 API#

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

列出项目#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

查询参数：

参数类型描述
limitint返回的最大项目数（默认：20，最大：500）

获取项目#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

返回 project 对象、每个模型摘要（状态、指标、轮次、权重、训练参数）的 models 数组以及 isOwner。

创建项目#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

字段类型必填描述
projectstring是Platform URL 中使用的项目名称
namestring是显示名称（最多 100 个字符）
descriptionstring否描述（最多 1000 个字符）
visibilitystring否public 或 private
tagsarray否最多 50 个标签
licensestring否项目许可证标识符
metadata对象否自定义 JSON 元数据
ownerstring否团队工作空间句柄；默认为你的个人工作空间
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

响应（201）： id、owner、project、region。

更新项目#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

接受的字段：name、description、visibility、metadata、tags、license、archived、iconColor、iconLetter、viewPreferences 和 starred。

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

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

删除项目#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

将项目及其模型移至回收站，并返回 cascadedModels。

克隆项目#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

克隆可访问的项目及其已完成的模型。可选正文接受 project、name、description、visibility、license 以及目标 owner。

Models API#

管理训练好的 YOLO 模型——查看指标、下载权重、运行推理并监控训练。请参阅 模型文档。

列出项目中的模型#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

查询参数：

参数类型描述
limitint返回的最大模型数（默认：20，最大：100）

获取模型#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

查询参数：

参数类型描述
analysisint设置为 1 以返回每张图像的验证分析，而不是模型本身

默认响应包含 model 对象——状态、任务、指标、trainArgs、trainResults、classNames、computeCost、metadata 等——外加 isOwner。

创建模型#

POST /api/models

Python SDK: client.models.create(body=...)

创建一个未训练的模型记录，你可以为其附加权重或进行训练。

字段类型必填描述
projectstring是目标项目名称
ownerstring否工作区句柄；默认为你的个人工作区
modelstring否Platform URL 中使用的模型名称；省略时自动生成
namestring否显示名称（仅在与 model 一起使用时接受）
descriptionstring否描述（最多 1000 个字符）
taskstring否detect、segment、semantic、depth、classify、pose 或 obb
metadata对象否自定义 JSON 元数据
trainArgs对象否要记录的训练参数
metrics对象否诸如 mAP50、mAP50-95、precision、recall 等指标
epochs数字否已训练模型的轮次计数
versionstring否版本标签（最多 50 个字符）

响应（201）： id、owner、project、model、region。

模型文件上传

要附加 .pt 权重，请使用 assetType: "models" 请求带签名的上传 URL，并将此模型的 id 作为 assetId，将文件 PUT 上传到返回的 URL，然后使用返回的 sessionId 调用 POST /api/upload/complete。

更新模型#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

接受的字段包括 name、description、color、metadata、status、license、datasetSlug、trainArgs、trainResults、epochs、bestEpoch、bestFitness、version、trainingError 和 starred。

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

自定义 metadata 与训练拥有的字段（如 trainArgs、environment 和 trainResults）分开，并使用与数据集元数据相同的大小限制。

删除模型#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

将模型移动到 回收站 30 天。

下载模型文件#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

返回模型权重的短期签名 URL。

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

克隆模型#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

将可访问的模型复制到现有项目中。

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}
字段类型必填描述
projectstring是目标项目名称
ownerstring否目标工作区；默认为你的个人工作区
modelstring否目标模型名称
namestring否目标显示名称
descriptionstring否克隆的描述

运行推理#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

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

多部分表单：

参数类型默认值范围描述
file文件--图像或视频文件（除非设置了 source，否则为必填）
conffloat0.250.01 – 1.0最低置信度阈值
ioufloat0.70.0 – 0.95NMS IoU 阈值
imgszint64032 – 1280输入图像尺寸（以像素为单位）
normalize布尔值false-将边界框坐标返回为 0 – 1
decimalsint50 – 10坐标值的小数精度
bitsint88, 12, 16深度图量化，仅限深度模型
sourcestring--图像 URL 或 base64 字符串（file 的替代方案）

提供 file 或 source。深度模型还接受 bits（8、12 或 16）来选择深度图的 PNG 量化。超出服务输入限制的请求将返回 413。

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

响应：

images 中的每个条目都包含 shape、speed、results，对于密集预测任务，还包含 semantic_mask 或 depth PNG 负载（深度值为 pixel × max / divisor，默认 8 位图的除数为 255，当 bits 为 12 或 16 时为 65535）。metadata 对象报告图像数量、函数耗时、任务和服务版本。绝不返回内部模型路径。

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

检查训练进度#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

返回包含状态、轮次进度、耗时、计算详情、训练参数、轮次指标和安全错误详情的 job，或者在模型从未训练过时返回 null。公共项目中的模型无需认证即可读取。

取消训练#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

终止正在运行的计算实例并标记任务已取消。当训练不再处于活动状态时返回 409。

Training API#

在云 GPU 上启动 YOLO 训练并实时监控进度。请参阅云训练文档。

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../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

获取 GPU 可用性#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

按 GPU ID 返回当前的库存状态。公开且无需认证；传递 managed=true 以包含托管训练容量（这需要 API 密钥）。

开始训练#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

字段类型必填描述
modelIdstring是要训练的模型的 ID
trainArgs对象是YOLO 训练参数；model、data 和 epochs 是必需的
gpuTypestring否要使用的云 GPU（默认：rtx-4090）
captureDatasetVersion布尔值否为此次运行保存一个不可变的的数据集版本（默认：false）
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://acme-vision/datasets/warehouse",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

响应：

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

当你的点数余额过低时，训练返回 402；当请求的 GPU 没有可用容量时，返回 503。

GPU 类型

提供 26 种 GPU 类型，从 rtx-2000-ada 到 b300，包括 rtx-4090、l40s、a100-80gb-pcie、a100-80gb-sxm、rtx-pro-6000、h100-sxm、h200-sxm 和 b200。有关包含价格的完整列表，请参阅云训练。

导出 API#

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

列出导出项#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

查询参数：

参数类型描述
statusstring按 queued、starting、running、completed、failed 或 cancelled 筛选
limitint要返回的最大导出数（默认：20，最大：100）

创建导出#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

字段类型必填描述
formatstring是目标导出格式（见下表）
gpuTypestring条件项当 format 为 engine 时必填；请使用支持的 GPU 或 Jetson 目标
args对象否导出选项：imgsz、quantize、dynamic、simplify、opset、conf、iou、batch、workspace、nms、end2end、optimize、keras 和 name（针对 RKNN、QNN、Hailo 和 Ascend 格式的目标设备）
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

响应（201）： id、format、status（queued 或 running）、gpuType、region。已经在进行中的等效导出将返回 409。

支持的格式：

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

格式format 参数模型元数据参数
PyTorch-yolo26n.pt✅-
TorchScripttorchscriptyolo26n.torchscript✅imgsz, quantize, dynamic, nms, batch, device
ONNXonnxyolo26n.onnx✅imgsz, quantize, dynamic, simplify, opset, nms, batch, data, fraction, device
OpenVINOopenvinoyolo26n_openvino_model/✅imgsz, quantize, dynamic, nms, batch, data, fraction, device
TensorRTengineyolo26n.engine✅imgsz, quantize, dynamic, simplify, opset, workspace, nms, batch, data, fraction, device
CoreMLcoremlyolo26n.mlpackage✅imgsz, dynamic, quantize, nms, batch, device
TF SavedModelsaved_modelyolo26n_saved_model/✅imgsz, keras, quantize, opset, nms, batch, data, fraction, device
TF GraphDefpbyolo26n.pb❌imgsz, opset, batch, device
TF Edge TPUedgetpuyolo26n_edgetpu.tflite✅imgsz, quantize, opset, data, fraction, device
PaddlePaddlepaddleyolo26n_paddle_model/✅imgsz, batch, device
MNNmnnyolo26n.mnn✅imgsz, batch, dynamic, quantize, simplify, opset, nms, device
NCNNncnnyolo26n_ncnn_model/✅imgsz, quantize, batch, device
IMX500imxyolo26n_imx_model/✅imgsz, quantize, data, fraction, nms, device
RKNNrknnyolo26n_rknn_model/✅imgsz, batch, name, quantize, simplify, opset, data, fraction, device
ExecuTorchexecutorchyolo26n_executorch_model/✅imgsz, batch, device
Axeleraaxelerayolo26n_axelera_model/✅imgsz, batch, quantize, data, fraction, device
DEEPXdeepxyolo26n_deepx_model/✅imgsz, quantize, simplify, opset, data, optimize, device
Qualcomm QNNqnnyolo26n_qnn.onnx✅imgsz, batch, name, quantize, simplify, opset, data, fraction, device
LiteRTlitertyolo26n.tflite✅imgsz, quantize, batch, data, fraction, device
Hailohailoyolo26n_hailo_model/✅imgsz, name, quantize, data, fraction, simplify, conf, iou
Huawei Ascendascendyolo26n_ascend_model/✅imgsz, batch, name, quantize, opset, simplify, nms
Apple Core AIcoreaiyolo26n.aimodel✅imgsz, batch, quantize

获取导出状态#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

返回带有 status、format、args、gpuType、时间戳的 export 对象，并且一旦完成，将返回包含 size、downloadUrl 和 downloadFilename 的 file 对象。

取消或删除导出#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

取消正在进行的导出或删除已完成的导出及其文件。响应会报告具体发生了哪种情况：

{
    "success": true,
    "action": "cancelled"
}

Deployments API#

将模型部署到具有健康检查和监控功能的专用推理端点。请参阅端点文档。

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action 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/{owner}

Python SDK: client.deployments.list(owner)

查询参数：

参数类型描述
statusstringcreating、deploying、ready、stopping、stopped 或 failed
modelstring按 {project}/{model} 筛选，例如 inspection/v3
limitint要返回的最大部署数（默认：20，最大：100）

匿名调用者必须按单个公共模型进行筛选；列出整个工作区需要身份验证。

创建部署#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

请求体：

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}
字段类型必填描述
projectstring是包含该 Project 的项目
modelstring是要部署的模型
deploymentstring是Platform URL 中使用的部署名称
namestring是显示名称
regionstring是42 个受支持的部署区域之一

响应（201）： id、deployment、status（creating）、message 和 region。

资源调整大小

CPU、内存和实例扩缩容由 Platform 根据你的套餐限制进行管理，创建请求不接受资源配置。当前值会在每次读取部署时在 resources 对象中返回。

区域选择

选择靠近你的用户的区域以获得最低延迟。Platform UI 显示所有 42 个可用区域的延迟估计值。

获取部署#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

返回带有 status、statusMessage、region、serviceUrl 和 resources 的 deployment 对象。

启动、停止或替换部署#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

单个 action 字段选择操作：

{ "action": "start" }

替换会推出新修订版本，同时保留部署 ID、区域和端点 URL；如果推出失败，现有修订版本将保持活动状态。替换模型必须是权重可被你的密钥访问的已完成模型。完成的操作会返回带有 status、ready 或 stopped 的 200；仍在推出的操作会返回带有 deploying 或 stopping 的 202。

删除部署#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

永久移除推理端点。

健康检查#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

对端点进行 Ping 测试并预热，返回 healthy、latencyMs 以及上游的 status 代码。

在部署上运行推理#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

通过专用端点路由图像或视频。请求和响应契约与模型推理相匹配。

多部分表单：

参数类型默认值范围描述
file文件--图像或视频文件（除非设置了 source，否则为必填）
conffloat0.250.01 – 1.0最低置信度阈值
ioufloat0.70.0 – 0.95NMS IoU 阈值
imgszint64032 – 1280输入图像尺寸（以像素为单位）
normalize布尔值false-将边界框坐标返回为 0 – 1
decimalsint50 – 10坐标值的小数精度
bitsint88, 12, 16深度图量化，仅限深度模型
sourcestring--图像 URL 或 base64 字符串（file 的替代方案）

获取指标#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

查询参数：

参数类型描述
rangestring1h、6h、24h（默认）、7d 或 30d
sparkline布尔值返回精简的仪表板摘要而不是完整序列（默认：false）

完整响应包含 summary（请求总数、错误率、平均延迟和 p50/p95/p99 延迟）和 timeSeries（请求、错误、延迟、CPU、内存、实例数）。迷你图响应返回 requests24h、totalRequests、errorRate 和 avgLatencyMs。

获取日志#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

查询参数：

参数类型描述
severitystring逗号分隔：DEBUG、INFO、NOTICE、WARNING、ERROR、CRITICAL、ALERT、EMERGENCY
limitint要返回的条目（默认：50，最大：200）
pageTokenstring来自前一个响应的分页令牌

回收站 API#

查看、还原和永久删除软删除的项目、数据集和模型。项目在 30 天后将被自动清除。请参阅回收站文档。

列出回收站项目#

GET /api/trash

Python SDK: client.lifecycle.trash()

查询参数：

参数类型描述
typestringall（默认）、project、dataset 或 model
pageint页码（默认：1）
limitint每页项目数（默认：50，最大：200）

响应包括 items（每个都带有 daysRemaining）、total、page、limit、totalPages 以及按类型统计总数的 summary。

恢复项目#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

还原项目还会还原与其一起放入回收站的模型，报告为 restoredModels。

永久删除#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

删除单个项目：

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

或者清空整个回收站：

{
    "all": true
}

响应报告 deletedCount，并在相关时报告 cascadedModels 和 survivingDeployments。

不可逆

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

上传 API#

使用签名 URL 将文件直接上传到云存储。完成模型上传会附加其权重；完成数据集归档上传会记录会话，然后将其传递给数据集引入。请参阅数据文档。

获取预签名上传 URL#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

请求体：

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}
字段类型必填描述
assetTypestring是datasets、models、images 或 videos
assetIdstring是目标数据集或模型的 ID
filenamestring是原始文件名（最多 256 个字符）
contentTypestring是MIME 类型
totalBytes数字是文件大小（字节）
数据集归档文件名

当 assetType 为 datasets 时，filename 必须以 .zip、.tar、.tar.gz、.tgz 或 .ndjson 结尾。上传前将零散图像打包到归档中。

响应：

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

使用 PUT 请求将文件上传到 uploadUrl，并使用你声明的相同 Content-Type。

完成上传#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

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

响应： success 以及带有 size 和 contentType 的 file 对象。对于模型，这会附加权重；对于数据集归档，请接着调用引入以开始处理。

存储集成 API#

连接只读的 Google Cloud Storage、Amazon S3 或 Azure Blob Storage 账户并将其作为数据集源进行浏览。请参阅集成文档。

列出集成#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

返回 integrations，每个都带有 id、provider、credentialIdentity、targets 和 createdAt。绝不返回凭据。

发现位置#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

列出使用所提供凭据可读的存储桶或容器，而不保存它们。

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

响应： {"targets": ["my-bucket", "another-bucket"]}

连接存储#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

与发现相同的凭据结构，外加一个必需的包含 1-50 个存储桶或容器名称的 targets 数组。返回带有存储集成的 201。临时 S3 凭据（ASIA 访问密钥）将被拒绝。

浏览对象#

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

Python SDK: client.storage_integrations.objects(id, target=...)

查询参数：

参数类型必填描述
targetstring是存储桶或容器名称
prefixstring否文件夹前缀（最多 1024 个字符）
cursorstring否来自先前页面的提供商分页游标

返回 entries（每个 kind 都是 folder 或 file）以及用于下一页的可选 cursor。

断开存储连接#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

移除保存的凭据而不删除提供商数据。已连接的数据集保持可见，但在重新连接相同的存储账户之前，其文件将保持不可用。需要工作区管理员访问权限。

数据集导入 API#

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

预览 Roboflow 导入#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

将 Roboflow API 密钥解析为导入计划：工作区详细信息、将要导入的 newDatasets、已跳过、不支持以及未解析的项目计数、bytesTotal 以及你的 storage 容量余量。Roboflow API 密钥是从正文中读取的，不会持久化存储。

{
    "apiKey": "ROBOFLOW_API_KEY"
}

从 Roboflow 导入#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

使用预览返回的项目，为最多 500 个选定的 Roboflow 项目版本排队注入任务。

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

响应（201）： imported、failed 和 skipped 数组。导入需要存储容量余量，并且每个数据集必须符合你套餐的单次导入大小限制。

账号 API#

检查你的 Platform 账号、密钥、存储和公开资料。请参阅设置文档。

账户摘要#

GET /api/account/summary

Python SDK: client.account.summary()

返回发出密钥的工作区的套餐、信用额度余额和资源计数。

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}
团队列表

teams 针对浏览器会话进行填充。API 密钥响应返回空列表，因为密钥的作用域已限定为单个工作区。

列出 API keys#

GET /api/api-keys

Python SDK: client.account.api_keys()

返回密钥所在工作区的 keys 以及 keyId、name、keyPrefix 和 createdAt。通过 API 密钥身份验证的请求仅接收元数据；完整的密钥值会显示在 Platform UI 的设置 > API 密钥中（这也是创建和撤销密钥的地方），供工作区所有者查看。

检查存储使用情况#

GET /api/storage

Python SDK: client.account.storage()

查询参数：

参数类型描述
details布尔值包含存储空间占用最大的十个对象（默认：false）

响应：

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

获取公开的用户个人资料#

GET /api/users

Python SDK: client.account.profile(username=...)

查询参数：

参数类型必填描述
usernamestring是要查找的用户名

返回包含 followerCount 的公开 user 个人资料，对于经过身份验证的调用者，还会返回 isFollowed。

关注或取消关注用户#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

响应： followed 和更新后的 followerCount。

账单 API#

检查套餐使用情况和你的信用账目。请参阅计费文档。

货币单位

计费金额是以美分为单位的整数，其中 100 = $1.00。

查看套餐和使用情况#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

返回 plan（ID、状态、计费周期、周期结束时间）、metrics（存储限制和使用情况）、trainingCredit、features、creditsCents 以及席位计数。

查看交易记录#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

查询参数：

参数类型描述
fromstring最早交易时间戳（ISO 8601）
tostring最新交易时间戳（ISO 8601）

每笔交易包含 id、type（例如 purchase、training、monthly_grant 或 refund）、amountCents、balanceAfter、createdAt、可选的 receiptUrl，以及用于训练费用的模型上下文。绝不会返回内部计费详细信息。

探索 API#

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

搜索公共内容#

GET /api/explore/search

Python SDK: client.explore.search()

查询参数：

参数类型描述
qstring搜索词（最多 200 个字符）
typestringall（默认）、projects 或 datasets
sortstringnewest（默认）、oldest、stars、name-asc、name-desc、count-desc、count-asc
offsetint要跳过的结果数（默认：0）
limitint每种资源类型的最大结果数（默认：20，最大：100）
taskstring逗号分隔的任务过滤器：detect、segment、semantic、depth、classify、pose、obb
authorstring所有者用户名过滤器
starred布尔值仅返回经过身份验证的调用者加星标的内容；需要 API 密钥

响应： projects、datasets 和 hasMore。

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

Python SDK#

ultralytics-platform 是一个根据 OpenAPI 契约生成的强类型 Python 客户端，每个端点对应一个方法（client.datasets.list、client.models.predict、client.exports.create 等）。每个方法按位置接收路径参数，其他输入作为关键字参数，并支持可选的每请求 timeout 和 extra_headers。

pip install "ultralytics-platform>=0.1.5" # Python 3.11+
from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform 为 async/await 代码公开了相同的资源树，不成功的响应会引发带有 status_code、body 以及解析后 json 的 APIError，连接失败则会引发 APIConnectionError。请参阅 SDK 仓库了解完整的 README。

Python 集成#

对于训练和推理工作流，请使用 Ultralytics Python 软件包，它会自动处理身份验证、上传和实时指标流式传输。

安装与设置#

pip install "ultralytics>=8.4.120"

验证安装：

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

常见问题解答#

  • 使用 Platform URL 中显示的所有者和名称段。位于 https://platform.ultralytics.com/acme-vision/inspection/v3 处的模型即为 GET /api/models/acme-vision/inspection/v3。数据库 ID 仍然会在响应中返回（作为 id），并且少数路由直接使用它们——图像路由使用 imageId，上传使用 assetId，而 POST /api/training/start 使用 modelId。

  • 这取决于集合。大多数列表端点接受 limit：

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

    数据集图像、聚类和探索搜索使用带有 limit 的 offset，并报告 hasMore：

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

    遍历非常大的图像集时，最好使用作为 nextCursor 返回的光标：

    curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets/acme-vision/warehouse/images?limit=1000&includeTotal=false&cursor=LAST_IMAGE_ID"

    回收站使用 page，部署日志使用作为 nextPageToken 返回的不透明 pageToken。

  • 是的。此页面上的每个操作都是一个普通的 HTTPS 请求，完整的契约已作为 OpenAPI 3.2 发布在 platform.ultralytics.com/openapi.json 上，你可以将其提供给任何语言的客户端生成器。ultralytics-platform 软件包正是如此：一个从契约生成的强类型客户端，而 ultralytics 软件包在训练和推理的基础上增加了实时指标流式传输和自动模型上传功能。仅限浏览器会话的账户流程（例如账单结算和团队管理）仍保留在 Platform UI 中。

  • 使用 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")

  • 404 意味着资源不存在或者你的密钥完全不可见。403 意味着找到了资源，但操作需要的访问权限超出了你的密钥所拥有的权限——例如修改数据集的编辑者访问权限、删除部署的所有者访问权限、断开存储连接的管理人员访问权限，或者用于导出和部署的更高套餐或配额。

  • 读取公开数据集、项目和模型（包括其图像、带签名的图像 URL、类别统计信息、嵌入状态、聚类布局和导出列表）；检查公开模型上的训练进度；下载公开模型的文件的；在公开模型上运行推理；查找公开用户的个人资料；列出过滤至一个公开模型的部署；以及搜索探索。GET /api/training/gpu-availability 是完全公开的，除非你请求托管容量。其他所有内容都需要密钥，并且在公开端点上提供密钥也会暴露出你的私有资源。

贡献者
GLglenn-jocher38LAlaodouya2SEsergiuwaxmann2MYmykolaxboiko2AMamanharshx1AMambitious-octopus1ONonuralpszr1RAraimbekovm1LALaughing-q1

评论