REST API 参考

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

Ultralytics Platform Api Overview

快速入门

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

交互式 API 文档

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

API 概述

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

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

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

身份验证

数据集、项目、模型、训练、导出和预测等资源 API 使用 API 密钥进行身份验证。公共端点（列出公共数据集、项目和模型）支持无需密钥的匿名读取访问。面向账户的路由（包括活动、设置、团队、账单和 GDPR 流程）目前需要经过身份验证的浏览器会话，无法通过 API 密钥使用。

获取 API 密钥

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

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

授权请求头

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

Authorization: Bearer YOUR_API_KEY

API Key 格式

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

示例

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

基础 URL

所有 API 端点均使用：

https://platform.ultralytics.com/api

速率限制

API 强制执行基于 API 密钥的速率限制（滑动窗口，由 Upstash Redis 支持），以防止滥用，同时确保合法使用不受限制。匿名流量还受到 Vercel 平台级滥用控制的额外保护。

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

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

API 密钥限制

速率限制是根据所调用的端点自动应用的。高负载操作有更严格的限制以防止滥用，而标准 CRUD 操作则享有宽裕的默认配额：

端点	限制	适用范围
默认	100 次请求/分钟	所有未列在下方的端点（列表、获取、创建、更新、删除）
训练	10 次请求/分钟	启动云端训练任务 (`POST /api/training/start`)
上传	10 次请求/分钟	文件上传、签名 URL 和数据集摄取
预测 (Predict)	20 次请求/分钟	共享模型推理 (`POST /api/models/{id}/predict`)
导出	20 次请求/分钟	模型格式导出 (`POST /api/exports`)、数据集 NDJSON 导出以及版本创建
下载	30 次请求/分钟	模型权重文件下载 (`GET /api/models/{id}/download`)
专用	无限	专用端点 — 你自己的服务，无 API 限制

每个类别都有一个独立于每个 API 密钥的计数器。例如，发出 20 个预测请求不会影响你的 100 次请求/分钟的默认配额。

专用端点（无限）

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

处理速率限制

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

响应格式

成功响应

响应返回带有资源特定字段的 JSON：

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

错误响应

{
    "error": "Dataset not found"
}

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

数据集 API

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

列出数据集

GET /api/datasets

查询参数：

参数	类型	描述
`username`	字符串	按用户名过滤
`slug`	字符串	通过 slug 获取单个数据集
`limit`	整数	每页显示的项数（默认：20，最大：500）
`owner`	字符串	工作区所有者用户名

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

响应：

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

获取数据集

GET /api/datasets/{datasetId}

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

创建数据集

POST /api/datasets

请求主体：

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

支持的任务

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

更新数据集

PATCH /api/datasets/{datasetId}

请求主体（部分更新）：

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

删除数据集

DELETE /api/datasets/{datasetId}

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

克隆数据集

POST /api/datasets/{datasetId}/clone

创建包含所有图像和标签的数据集副本。仅可克隆公开数据集。需要活跃的平台浏览器会话——无法通过 API 密钥使用。

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

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

导出数据集

GET /api/datasets/{datasetId}/export

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

查询参数：

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

响应：

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

创建数据集版本

POST /api/datasets/{datasetId}/export

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

请求主体：

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

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

响应：

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

更新版本描述

PATCH /api/datasets/{datasetId}/export

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

请求主体：

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

响应：

{
    "ok": true
}

获取类别统计信息

GET /api/datasets/{datasetId}/class-stats

返回类别分布、位置热力图和维度统计信息。结果最多缓存 5 分钟。

响应：

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

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

GET /api/datasets/{datasetId}/models

返回使用此数据集训练过的模型。

响应：

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

自动标注数据集

POST /api/datasets/{datasetId}/predict

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

请求主体：

字段	类型	必填	描述
`imageHash`	字符串	是	要标注的图像哈希值
`modelId`	字符串	否	用于推理的模型 ID
`confidence`	浮点数	否	置信度阈值（默认：0.25）
`iou`	浮点数	否	IoU 阈值（默认：0.45）

数据集接入

POST /api/datasets/ingest

创建数据集接入任务，以处理上传的 ZIP 或 TAR 文件（包括 .tar.gz 和 .tgz），其中包含图像和标签。

graph LR
    A[Upload Archive] --> B[POST /api/datasets/ingest]
    B --> C[Process Archive]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

数据集图像

列出图像

GET /api/datasets/{datasetId}/images

查询参数：

参数	类型	描述
`split`	字符串	按拆分过滤：`train`、`val`、`test`
`offset`	整数	分页偏移量（默认：0）
`limit`	整数	每页显示的项数（默认：50，最大：5000）
`sort`	字符串	排序顺序：`newest`、`oldest`、`name-asc`、`name-desc`、`height-asc`、`height-desc`、`width-asc`、`width-desc`、`size-asc`、`size-desc`、`labels-asc`、`labels-desc`（部分排序对超过 10 万张图像的数据集禁用）
`hasLabel`	字符串	按标签状态过滤（`true` 或 `false`）
`hasError`	字符串	按错误状态过滤（`true` 或 `false`）
`search`	字符串	按文件名或图像哈希值搜索
`includeThumbnails`	字符串	包含已签名的缩略图 URL（默认：`true`）
`includeImageUrls`	字符串	包含已签名的完整图像 URL（默认：`false`）

获取已签名的图像 URL

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

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

删除图像

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

获取图像标签

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

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

更新图像标签

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

请求主体：

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

坐标格式

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

批量图像操作

在数据集内移动拆分（训练集/验证集/测试集）之间的图像：

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

批量删除图像：

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

项目 API

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

列出项目

GET /api/projects

查询参数：

参数	类型	描述
`username`	字符串	按用户名过滤
`limit`	整数	每页显示的项数
`owner`	字符串	工作区所有者用户名

获取项目

GET /api/projects/{projectId}

创建项目

POST /api/projects

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

更新项目

PATCH /api/projects/{projectId}

删除项目

DELETE /api/projects/{projectId}

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

克隆项目

POST /api/projects/{projectId}/clone

将公开项目（及其所有模型）克隆到你的工作区。需要活跃的平台浏览器会话——无法通过 API 密钥使用。

项目图标

上传项目图标（带有图像文件的 multipart 表单）：

POST /api/projects/{projectId}/icon

移除项目图标：

DELETE /api/projects/{projectId}/icon

两者均需要处于活跃状态的平台浏览器会话 —— 无法通过 API 密钥使用。

模型 API

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

列出模型

GET /api/models

查询参数：

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

列出已完成的模型

GET /api/models/completed

返回已完成训练的模型（用于模型选择器和部署）。

获取模型

GET /api/models/{modelId}

创建模型

POST /api/models

JSON 正文：

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

模型文件上传

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

更新模型

PATCH /api/models/{modelId}

删除模型

DELETE /api/models/{modelId}

下载模型文件

GET /api/models/{modelId}/files

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

克隆模型

POST /api/models/{modelId}/clone

将公共模型克隆到你的项目之一。需要处于活跃状态的平台浏览器会话 —— 无法通过 API 密钥使用。

请求主体：

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

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

追踪下载

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

追踪模型下载分析。

运行推理

POST /api/models/{modelId}/predict

多部分表单：

字段	类型	描述
`file`	文件	图像文件（JPEG、PNG、 WebP）
`conf`	浮点数	置信度阈值（默认：0.25）
`iou`	浮点数	IoU 阈值（默认：0.7）
`imgsz`	整数	图像像素尺寸（默认：640）

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

响应：

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

获取预测令牌

POST /api/models/{modelId}/predict/token

仅限浏览器会话

此路由由应用内的“预测”选项卡使用，用于发布短效推理令牌，以便直接进行浏览器 → 预测服务调用（延迟更低，无 API 代理）。它需要处于活跃状态的平台浏览器会话，且无法通过 API 密钥使用。如需程序化推理，请使用你的 API 密钥调用 POST /api/models/{modelId}/predict。

预热模型

POST /api/models/{modelId}/predict/warmup

仅限浏览器会话

预热路由由“预测”选项卡使用，用于在用户首次推理之前在预测服务上预加载模型权重。它需要处于活跃状态的平台浏览器会话，且无法通过 API 密钥使用。

训练 API

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

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

开始训练

POST /api/training/start

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

GPU 类型

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

获取训练状态

GET /api/models/{modelId}/training

返回模型的当前训练作业状态、指标和进度。公共项目可匿名访问；私有项目需要处于活跃状态的平台浏览器会话（此路由不接受 API 密钥认证）。

取消训练

DELETE /api/models/{modelId}/training

终止正在运行的计算实例并将作业标记为已取消。需要处于活跃状态的平台浏览器会话 —— 无法通过 API 密钥使用。

部署 API

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

各路由对 API 密钥的支持

仅 GET /api/deployments、POST /api/deployments、GET /api/deployments/{deploymentId} 和 DELETE /api/deployments/{deploymentId} 支持 API 密钥认证。predict、health、logs、metrics、start 和 stop 子路由需要处于活跃状态的平台浏览器会话 —— 它们是应用内 UI 的便捷代理。如需程序化推理，请使用你的 API 密钥直接调用部署自身的端点 URL（例如 https://predict-abc123.run.app/predict）。专用端点不受速率限制。

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

列出部署

GET /api/deployments

查询参数：

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

创建部署

POST /api/deployments

请求主体：

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

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

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

默认资源

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

选择区域

选择靠近用户的位置以获得最低延迟。平台 UI 显示所有 43 个可用区域的延迟估算值。

获取部署

GET /api/deployments/{deploymentId}

删除部署

DELETE /api/deployments/{deploymentId}

启动部署

POST /api/deployments/{deploymentId}/start

恢复已停止的部署。

停止部署

POST /api/deployments/{deploymentId}/stop

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

健康检查

GET /api/deployments/{deploymentId}/health

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

在部署上运行推理

POST /api/deployments/{deploymentId}/predict

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

多部分表单：

字段	类型	描述
`file`	文件	图像文件（JPEG、PNG、 WebP）
`conf`	浮点数	置信度阈值（默认：0.25）
`iou`	浮点数	IoU 阈值（默认：0.7）
`imgsz`	整数	图像像素尺寸（默认：640）

获取指标

GET /api/deployments/{deploymentId}/metrics

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

查询参数：

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

获取日志

GET /api/deployments/{deploymentId}/logs

查询参数：

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

监控 API

仅限浏览器会话

GET /api/monitoring 是仅限 UI 的路由，需要有效的平台浏览器会话。它不接受 API 密钥认证。请通过各部署专用的路由（也仅限浏览器会话）查询单个部署指标，或者在已部署的 Cloud Run 服务上使用 Cloud Monitoring exports 进行程序化访问。

聚合指标

GET /api/monitoring

返回所有用户部署的聚合指标：总请求数、活跃部署数、错误率和平均延迟。

导出 API

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

导出列表

GET /api/exports

查询参数：

参数	类型	描述
`modelId`	字符串	模型 ID（必需）
`status`	字符串	按状态过滤
`limit`	整数	最大结果数（默认：20，最大：100）

创建导出

POST /api/exports

请求主体：

字段	类型	必填	描述
`modelId`	字符串	是	源模型 ID
`format`	字符串	是	导出格式（见下表）
`gpuType`	字符串	条件选项	当 `format` 为 `engine` (TensorRT) 时必需
`args`	对象	否	导出参数（`imgsz`、`half`、`dynamic` 等）

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

支持的格式：

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

获取导出状态

GET /api/exports/{exportId}

取消导出

DELETE /api/exports/{exportId}

跟踪导出下载

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

活动 API

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

仅限浏览器会话

活动路由由平台 UI 的浏览器认证请求提供支持。它们不作为公共 API 公开，不接受 API 密钥认证，文档中记录的路由形态仅供参考。请在平台 UI 中使用活动信息流来查看、标记或存档事件。

列出活动

GET /api/activity

查询参数：

参数	类型	描述
`limit`	整数	页面大小（默认：20，最大：100）
`page`	整数	页码（默认：1）
`archived`	布尔值	`true` 表示存档标签页，`false` 表示收件箱
`search`	字符串	事件字段中的不区分大小写搜索

标记事件为已读

POST /api/activity/mark-seen

请求主体：

{
    "all": true
}

或传入特定 ID：

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

存档事件

POST /api/activity/archive

请求主体：

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

或传入特定 ID：

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

回收站 API

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

列出回收站

GET /api/trash

查询参数：

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

恢复项目

POST /api/trash

请求主体：

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

永久删除项目

DELETE /api/trash

请求主体：

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

不可逆

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

清空回收站

DELETE /api/trash/empty

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

身份验证

DELETE /api/trash/empty 需要已认证的浏览器会话，且不能通过 API 密钥使用。请改用 UI 中的 Empty Trash（清空回收站）按钮。

账单 API

查看你的信用余额、购买额度、查看交易历史并配置自动充值。请参阅账单文档。

货币单位

Billing amounts use cents (creditsCents) where 100 = $1.00.

获取余额

GET /api/billing/balance

查询参数：

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

响应：

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

获取使用情况摘要

GET /api/billing/usage-summary

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

获取交易记录

GET /api/billing/transactions

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

查询参数：

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

创建结账会话

POST /api/billing/checkout-session

请求主体：

{
    "amount": 25,
    "owner": "team-username"
}

字段	类型	必填	描述
`amount`	数字	是	美元金额（$5-$1000）
`owner`	字符串	否	用于工作区充值的团队用户名（需要管理员角色）

为额度购买创建结账会话。

创建订阅结账

POST /api/billing/subscription-checkout

为 Pro 订阅升级创建结账会话。

请求主体：

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

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

取消或恢复订阅

DELETE /api/billing/subscription-checkout

默认在周期结束时取消 Pro 订阅。发送 {"resume": true} 可在计费周期结束前恢复已安排的取消。

请求主体：

{
    "resume": true
}

自动充值

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

获取自动充值配置

GET /api/billing/auto-topup

查询参数：

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

更新自动充值配置

PATCH /api/billing/auto-topup

请求主体：

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

支付方式

列出付款方式

GET /api/billing/payment-methods

创建设置意向 (Setup Intent)

POST /api/billing/payment-methods/setup

返回用于添加新付款方式的客户端密钥。

设置默认付款方式

POST /api/billing/payment-methods/default

请求主体：

{
    "paymentMethodId": "pm_123"
}

更新账单信息

PATCH /api/billing/payment-methods

请求主体：

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

删除付款方式

DELETE /api/billing/payment-methods/{id}

存储 API

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

仅限浏览器会话

存储路由需要活跃的平台浏览器会话，无法通过 API Key 访问。请使用 UI 中的 Settings > Profile 页面进行交互式明细查看。

获取存储信息

GET /api/storage

响应：

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

上传 API

使用签名 URL 将文件直接上传到云存储，以实现快速、可靠的传输。使用两步流程：获取签名 URL，然后上传文件。请参阅 Data documentation。

获取签名上传 URL

POST /api/upload/signed-url

请求用于将文件直接上传到云存储的签名 URL。签名 URL 可绕过 API 服务器进行大文件传输。

请求主体：

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

字段	类型	描述
`assetType`	字符串	资产类型：`models`、`datasets`、`images`、`videos`
`assetId`	字符串	目标资产的 ID
`filename`	字符串	原始文件名
`contentType`	字符串	MIME 类型
`totalBytes`	整数	以字节为单位的文件大小

响应：

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

完成上传

POST /api/upload/complete

通知平台文件上传已完成，以便开始处理。

请求主体：

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API Keys API

管理用于程序化访问的 API Key。请参阅 API Keys documentation。

列出 API Key

GET /api/api-keys

创建 API Key

POST /api/api-keys

请求主体：

{
    "name": "training-server"
}

删除 API Key

DELETE /api/api-keys

查询参数：

参数	类型	描述
`keyId`	字符串	要撤销的 API Key ID

示例：

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

团队与成员 API

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

列出团队

GET /api/teams

创建团队

POST /api/teams/create

请求主体：

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

列出成员

GET /api/members

返回当前工作区的成员。

邀请成员

POST /api/members

请求主体：

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

成员角色

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

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

更新成员角色

PATCH /api/members/{userId}

移除成员

DELETE /api/members/{userId}

转移所有权

POST /api/members/transfer-ownership

邀请

接受邀请

POST /api/invites/accept

获取邀请信息

GET /api/invites/info

查询参数：

参数	类型	描述
`token`	字符串	邀请令牌

撤销邀请

DELETE /api/invites/{inviteId}

重新发送邀请

POST /api/invites/{inviteId}/resend

探索 API

搜索并浏览社区分享的公共数据集和项目。请参阅 Explore documentation。

搜索公共内容

GET /api/explore/search

查询参数：

参数	类型	描述
`q`	字符串	搜索查询
`type`	字符串	资源类型：`all`（默认）、`projects`、`datasets`
`sort`	字符串	排序顺序：`stars`（默认）、`newest`、`oldest`、`name-asc`、`name-desc`、`count-desc`、`count-asc`
`offset`	整数	分页偏移量（默认：0）。结果每页返回 20 个项目。

侧边栏数据

GET /api/explore/sidebar

为探索侧边栏返回精选内容。

用户与设置 API

管理你的个人资料、API Key、存储使用情况和数据隐私设置。请参阅 Settings documentation。

按用户名获取用户

GET /api/users

查询参数：

参数	类型	描述
`username`	字符串	要查找的用户名

关注或取消关注用户

PATCH /api/users

请求主体：

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

检查用户名可用性

GET /api/username/check

查询参数：

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

设置

GET /api/settings
POST /api/settings

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

个人资料图标

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

上传或移除个人资料头像。

入职引导

POST /api/onboarding

完成入职流程（设置数据区域、用户名）。

请求导出你的所有数据或永久删除你的账户。请参阅 Settings documentation。

GET /api/gdpr

查询参数：

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

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

开始导出或删除流程

POST /api/gdpr

请求主体：

{
    "action": "export"
}

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

团队工作区可选：

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

不可逆操作

账户删除后永久生效且无法撤销。所有数据、模型和部署都将被删除。

错误代码

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

Python 集成

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

安装与设置

pip install ultralytics

验证安装：

yolo check

软件包版本要求

平台集成要求 ultralytics>=8.4.35。旧版本将无法与平台配合使用。

身份验证

yolo settings api_key=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, half=True)

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

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

验证：

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

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

Webhooks

平台使用内部 Webhooks 将实时训练指标从 ultralytics Python SDK（运行在云端 GPU 或远程/本地机器上）流式传输回平台——包括 epoch 级的损失、mAP、系统状态和完成进度。这些 Webhooks 通过每个训练任务配置的 HMAC webhookSecret 进行身份验证，并不打算供用户应用程序使用。

在你的环境中使用

所有计划：通过 ultralytics SDK 进行的训练进度（实时指标、完成通知）在每个计划中都可自动运行——只需在训练时设置 project=username/my-project name=my-run，SDK 就会将事件流式传输回平台。无需进行用户端的 Webhook 注册。

面向用户的 Webhook 订阅（向你控制的 URL 发送 POST 回调）已列入 Enterprise 路线图，目前尚未提供。在此期间，请轮询 GET /api/models/{modelId}/training 以获取状态，或在 UI 中使用活动订阅源。

常见问题解答

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

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

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

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

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

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

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

我可以在没有 SDK 的情况下使用 API 吗？

可以，所有功能都可通过 REST 使用。Python SDK 是一个便捷的封装库，它增加了实时指标流传输和自动模型上传等功能。你还可以通过 platform.ultralytics.com/api/docs 交互式地探索所有端点。

是否有 API 客户端库？

目前，请使用 Ultralytics Python 软件包或直接发起 HTTP 请求。其他语言的官方客户端库正在规划中。

如何处理速率限制？

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

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise Exception("Rate limit exceeded")

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

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

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

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

Contributors

GLglenn-jocher¹⁶ MYmykolaxboiko² RAraimbekovm¹ SEsergiuwaxmann¹ LALaughing-q¹

Created 4个月前Updated 3天前