Ultralytics YOLO27：

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

下面列出的每个端点都会展示其通过 client.<resource>.<method>(...) 调用的方式，该调用来自 ultralytics-platform SDK，此 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
资源描述关键操作
数据集带标注的图像集合CRUD、摄取、版本、类别、划分、克隆
图像单张图像及其标注读取、标注、移动划分、删除、自动标注
项目模型工作区CRUD、克隆
模型已训练的检查点CRUD、预测、下载、克隆、训练状态
训练云端 GPU 训练任务GPU 可用性、启动、进度、取消
导出格式转换任务创建、列出、查看状态、取消
部署专用推理端点创建、启动/停止/替换、预测、指标、日志
回收站软删除的资源列出、恢复、永久删除
存储云存储集成连接、发现、浏览、断开连接
账户计划、额度、存储、个人资料账户摘要、API 密钥、存储用量、用户查询
计费计划用量和账本用量摘要、交易记录
探索公共内容搜索搜索项目和数据集

身份验证#

大多数端点都需要 API 密钥。公开内容端点（读取公开数据集、项目或模型，列出公开数据集图像，对公开模型运行推理，或搜索 Explore）也接受匿名请求；提供密钥后，它们只会返回更多内容。

获取 API 密钥#

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

详细说明请参阅 API 密钥。

Authorization 标头#

将你的 API 密钥作为 bearer token 传入：

Authorization: Bearer YOUR_API_KEY
API 密钥格式

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

示例#

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

基础 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 次请求/分钟模型导出路由以及数据集导出/版本路由（读取数据集导出除外，读取数据集导出使用 GET，其采用默认限制）
Download30 次请求/分钟模型文件下载
变更10 次请求/分钟列出 API 密钥、连接或发现云存储，以及部署 PATCH 操作
填充20 次请求/分钟POST /api/datasets/{owner}/{dataset}/images（获取选定的一组图像）和 GET /api/images/{imageId}/similar
聚类10 次请求/分钟GET /api/datasets/{owner}/{dataset}/images/clustering 和 GET /api/models/{owner}/{project}/{model}/similar-images

仅限浏览器的 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 时，专用端点 不受 Platform API 密钥限流限制（例如 https://predict-abc123.run.app/predict）。此时吞吐量取决于已部署服务的配置。

处理限流

收到 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）
classNames数组否按索引顺序排列的类别名称（最多 25,000 个）
formatstring否标注格式：yolo（默认）、coco、raw、ndjson
visibilitystring否public 或 private
tags数组否最多 50 个标签，每个标签最多 50 个字符
licensestring否数据集许可证标识符
metadata对象否自定义 JSON 元数据
ownerstring否团队工作区句柄；默认为你的个人工作区
requireExactSlug布尔值否当 dataset 已被占用时，返回 409，而不是创建诸如 warehouse-2（默认 false）之类的带后缀的名称

响应会返回实际创建的 dataset 标识符，因此在上传之前请先读取它，除非你设置了 requireExactSlug。

支持的任务

创建或更新数据集时，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 可导出数据集的当前状态；如果自生成以来没有任何更改，则会重用缓存的导出结果。

查询参数：

参数类型描述
v整数已保存的版本号（从 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 二维布局，并使用 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。

自动标注数据集#

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK： client.datasets.create_batch(owner, dataset, model_id=...)

保存数据集版本，然后排队运行，使用模型对数据集的未标注图像进行标注，并返回 202。 请求体接受与单张图像端点相同的 modelId、confidence 和 iou 字段，外加 includeAnnotated （默认值为 false），以便同时标注已有标签的图像，还可提供可选的 classMapping 数组来给出 每个模型类别的对应数据集类别索引，或者用 null 来跳过它。现有的标签绝不会被更改，且运行费用按 实际处理的图像进行结算。402 意味着余额不足以支付预估费用，409 意味着数据集未准备好、 没有剩余图像可供标注或已有正在进行的运行，而 422 则意味着数据集没有类别：请在调用此端点之前使用 classes 端点创建类别，应用程序的“映射类别”步骤在启动运行前执行的就是这一操作。

在相同路径（client.datasets.batch(owner, dataset)）上的 GET 返回正在进行的运行及其进度，或者返回最后一次 已完成的运行直到其被清除；DELETE（client.datasets.delete_batch(owner, dataset)）取消正在进行的运行或 结算账单并清除已完成的摘要。

批量移动图像#

PATCH /api/images/bulk

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

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

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

文件名或内容冲突会返回 409，直到你为整个批次选择 skip、keep_both 或 replace 中的 conflictPolicy。响应会报告 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
tags数组否最多 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。

模型 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。单独传递 projectId 会将模型移动到同一拥有者的另一个项目中；响应在目标位置中会返回模型的 slug、 在该标识符已被占用的情况下返回 renamed: true，以及在模型仍在训练时返回 409。

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

多部分表单：

参数类型默认值范围描述
filefile--图像或视频文件（除非设置了 source，否则为必需）
conffloat0.250.01 – 1.0最小置信度阈值
ioufloat0.70.0 – 0.95NMS IoU 阈值
imgszint64032 – 1280输入图像大小（像素）
normalizeboolfalse-将边界框坐标作为 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。

训练 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、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

nms=None 默认对外部 NMS 使用原始输出。设置 nms=False 以选择可用的无 NMS 检测头；不支持的格式将回退到其本机输出路径。上面的 nms 条目标识了可以通过 nms=True 嵌入 NMS 的格式。

获取导出状态#

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

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

返回包含 status、format、args、gpuType、时间戳的 export 对象；完成后，还会包含一个 file 对象，其中包含 size、downloadUrl 和 downloadFilename。

取消或删除导出任务#

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

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

取消活动的导出任务，或删除已完成的导出任务及其文件。响应会报告所执行的操作：

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

部署 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是包含模型的项目
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=...)

通过专用端点处理图像或视频。请求和响应契约与 模型推理一致。

多部分表单：

参数类型默认值范围描述
filefile--图像或视频文件（除非设置了 source，否则为必需）
conffloat0.250.01 – 1.0最小置信度阈值
ioufloat0.70.0 – 0.95NMS IoU 阈值
imgszint64032 – 1280输入图像大小（像素）
normalizeboolfalse-将边界框坐标作为 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",
    "headers": { "x-goog-if-generation-match": "0" }
}

通过 PUT 请求将文件上传到 uploadUrl，使用你声明的相同 Content-Type 以及在 headers 中返回的每一个标头。 数据集上传 URL 的有效期为 12 小时且仅限创建：向同一个 URL 发送第二次 PUT 会返回 412，而在没有返回的标头的情况下发送 PUT 则会返回 400。

完成上传#

POST /api/upload/complete

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

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

响应： success 以及包含 size 和 contentType 的 file 对象。对于模型，这会附加权重；对于 数据集存档，下一步调用 导入 以开始处理。

当提供了 md5 时，系统会将其与存储的对象进行核对。如果不匹配，则返回 400；在尚未完成的会话中，它还会删除上传的文件并使会话保持未完成状态，因此请请求新的签名 URL 并重新 上传。已完成的数据集会话在其存档存在时可以再次完成，但具有 不同摘要的并发完成请求会返回 409；模型会话在完成后会被移除。checksum 作为模型文件元数据存储 ，不经过验证。

存储集成 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 密钥#

GET /api/api-keys

Python SDK： client.account.api_keys()

返回包含 keyId、name、keyPrefix 和 createdAt 的 keys，这些内容对应密钥所属的工作区。经过 API 密钥身份验证的 请求仅返回元数据；完整密钥值会在 Platform 界面的 设置 > 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是要查询的用户名

返回公开的 user 个人资料，其中包含 followerCount；对于经过身份验证的调用方，还包含 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.45" # Python 3.11+
from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by yolo login
    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 代码提供相同的资源树；失败的响应会引发 APIError，并包含 status_code、body 和解析后的 json；连接失败会引发 APIConnectionError。完整 README 请参阅 SDK 仓库。

Python 集成#

对于训练和推理工作流，请使用 Ultralytics Python 软件包，它可以自动处理身份验证、上传和实时指标流式传输。在 Python 3.11+ 上，pip install ultralytics 还会安装 ultralytics-platform SDK。当 model.train(project=...) 针对 Platform 时，训练回调会通过 SDK 的 client.training.metrics() 流式传输事件，并通过 OpenAPI 文档中的 client.models.upload_checkpoint()、POST /api/webhooks/training/metrics 和 POST /api/webhooks/models/upload 操作请求检查点上传 URL，因此你无需亲自调用任何内容。

安装和设置#

平台集成需要 Python>=3.11 和 ultralytics>=8.4.120：

pip install "ultralytics>=8.4.120"

验证安装：

yolo check

身份验证#

yolo login YOUR_API_KEY

使用 Platform 数据集#

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

推送到 Platform#

将结果发送到 Platform 项目：

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

同步内容：

  • 训练指标（实时）
  • 最终模型权重
  • 验证图表
  • 控制台输出
  • 系统指标
  • 训练参数与主机环境（主机名、操作系统、Python、硬件、git 提交、命令行）

API 示例#

从 Platform 加载模型：

# 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），并且有些路由会直接接收这些 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 界面中。

  • 使用 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-jocher40RAraimbekovm5LAlaodouya2SEsergiuwaxmann2MYmykolaxboiko2AMamanharshx1AMambitious-octopus1ONonuralpszr1LALaughing-q1

评论