REST API 参考

Q: How do I paginate large results?

使用 page 和 limit 参数：

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

快速入门

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

身份验证

所有 API 请求都需要通过 API 密钥进行身份验证。

获取 API 密钥

前往 设置 > API 密钥
点击 创建密钥
复制生成的密钥

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

授权头

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

Authorization: Bearer ul_your_api_key_here

示例

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

基础 URL

所有 API 端点均使用：

https://platform.ultralytics.com/api

速率限制

计划	请求数/分钟	请求数/天
免费版	60	1,000
Pro	300	50,000
企业版	自定义	自定义

响应中包含速率限制头：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

响应格式

所有响应均为 JSON 格式：

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

数据集 AP

列出数据集

GET /api/datasets

查询参数：

参数	类型	描述
`page`	整型	页码（默认值：1）
`limit`	整型	每页项目数（默认值：20）
`task`	字符串	按任务类型筛选

响应：

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

获取数据集

GET /api/datasets/{datasetId}

创建数据集

POST /api/datasets

正文：

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

删除数据集

DELETE /api/datasets/{datasetId}

导出数据集

POST /api/datasets/{datasetId}/export

返回 NDJSON 格式的下载 URL。

在数据集上训练模型

GET /api/datasets/{datasetId}/models

返回使用此数据集训练的模型列表，展示数据集与其生成的模型之间的关联关系。

响应：

{
    "success": true,
    "data": [
        {
            "id": "model_abc123",
            "name": "experiment-1",
            "projectId": "project_xyz",
            "trainedAt": "2024-01-15T10:00:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72
            }
        }
    ]
}

项目 AP

列出项目

GET /api/projects

获取项目

GET /api/projects/{projectId}

创建项目

POST /api/projects

正文：

{
    "name": "my-project",
    "description": "Detection experiments"
}

删除项目

DELETE /api/projects/{projectId}

模型 AP

列出模型

GET /api/models

查询参数：

参数	类型	描述
`projectId`	字符串	按项目筛选
`task`	字符串	按任务类型筛选

获取模型

GET /api/models/{modelId}

上传模型

POST /api/models

多部分表单：

字段	类型	描述
`file`	文件	模型 .pt 文件
`projectId`	字符串	目标项目
`name`	字符串	模型名称

删除模型

DELETE /api/models/{modelId}

下载模型

GET /api/models/{modelId}/files

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

运行推理

POST /api/models/{modelId}/predict

多部分表单：

字段	类型	描述
`file`	文件	图像文件
`conf`	浮点数	置信度阈值
`iou`	浮点数	IoU 阈值

响应：

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

训练 AP

开始训练

POST /api/training/start

正文：

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

获取训练状态

GET /api/models/{modelId}/training

取消训练

DELETE /api/models/{modelId}/training

部署 AP

列出部署

GET /api/deployments

查询参数：

参数	类型	描述
`modelId`	字符串	按模型筛选

创建部署

POST /api/deployments

正文：

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

获取部署

GET /api/deployments/{deploymentId}

启动部署

POST /api/deployments/{deploymentId}/start

停止部署

POST /api/deployments/{deploymentId}/stop

删除部署

DELETE /api/deployments/{deploymentId}

获取指标

GET /api/deployments/{deploymentId}/metrics

获取日志

GET /api/deployments/{deploymentId}/logs

查询参数：

参数	类型	描述
`severity`	字符串	信息, 警告, 错误
`limit`	整型	条目数量

导出 AP

列出导出

GET /api/exports

创建导出

POST /api/exports

正文：

{
    "modelId": "model_abc123",
    "format": "onnx"
}

支持的格式：

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

获取导出状态

GET /api/exports/{exportId}

活动 AP

track 并管理您账户的活动事件。

列出活动

GET /api/activity

查询参数：

参数	类型	描述
`startDate`	字符串	按起始日期筛选 (ISO)
`endDate`	字符串	按结束日期筛选 (ISO)
`search`	字符串	在事件消息中搜索

标记事件已读

POST /api/activity/mark-seen

归档事件

POST /api/activity/archive

回收站 AP

管理软删除资源（30 天保留期）。

列出回收站

GET /api/trash

恢复项目

POST /api/trash

正文：

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

清空回收站

POST /api/trash/empty

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

账单 AP

管理积分和订阅。

获取余额

GET /api/billing/balance

响应：

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

微美元

所有金额均以微美元（1,000,000 微美元 = 1.00 美元）计价，以便进行精确核算。

获取使用情况摘要

GET /api/billing/usage-summary

返回套餐详情、限制和使用指标。

创建结账会话

POST /api/billing/checkout-session

正文：

{
    "amount": 25
}

创建用于购买积分（5-1000 美元）的 Stripe 结账会话。

创建订阅结账

POST /api/billing/subscription-checkout

创建用于专业版订阅的 Stripe 结账会话。

创建门户会话

POST /api/billing/portal-session

返回用于订阅管理的 Stripe 账单门户网址。

获取支付历史

GET /api/billing/payments

返回 Stripe 的支付交易列表。

存储 AP

获取存储信息

GET /api/storage

响应：

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

用于数据导出和删除的 GDPR 合规性端点。

导出/删除账户数据

POST /api/gdpr

正文：

{
    "action": "export"
}

操作	描述
`export`	下载所有账户数据
`delete`	删除账户及所有数据

不可逆操作

账户删除是永久性的，无法撤销。所有数据、模型和部署都将被删除。

AP 密钥 AP

列出 AP 密钥

GET /api/api-keys

创建 AP 密钥

POST /api/api-keys

正文：

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

删除 AP 密钥

DELETE /api/api-keys/{keyId}

错误代码

代码	描述
`UNAUTHORIZED`	API 密钥无效或缺失
`FORBIDDEN`	权限不足
`NOT_FOUND`	资源未找到
`VALIDATION_ERROR`	请求数据无效
`RATE_LIMITED`	请求过多
`INTERNAL_ERROR`	服务器错误

Python

为便于集成，请使用 Ultralytics python 包。

安装与设置

pip install ultralytics

验证安装：

yolo check

软件包版本要求

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

身份验证

方法1：CLI （推荐）

yolo settings api_key=YOUR_API_KEY

方法二：环境变量

export ULTRALYTICS_API_KEY=YOUR_API_KEY

方法三：在代码中

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

使用平台数据集

包含以下内容的参考数据集： ul:// 统一资源标识符：

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

URI格式：

ul://{username}/{resource-type}/{name}

Examples:
ul://john/datasets/coco-custom     # Dataset
ul://john/my-project               # Project
ul://john/my-project/exp-1         # Specific model
ul://ultralytics/yolo26/yolo26n    # Official model

推送至平台

将结果发送至平台项目：

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://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/my-dataset")

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

Webhooks

Webhooks 会通知您的服务器平台事件：

事件	描述
`training.started`	训练任务已启动
`training.epoch`	周期已完成
`training.completed`	训练完成
`training.failed`	训练失败
`export.completed`	导出就绪

Webhook 设置在企业版套餐中可用。

常见问题

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

使用 page 和 limit 参数：

GET /api/datasets?page=2 &
limit=50

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

是的，所有功能均可通过 REST 访问。SDK 只是一个便捷的封装。

是否有API客户端库？

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

我如何处理速率限制？

实现指数退避：

import time


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

📅 创建于 20 天前 ✏️ 更新于 14 天前

REST API 参考

身份验证

获取 API 密钥

授权头

示例

基础 URL

速率限制

响应格式

错误响应

数据集 AP

列出数据集

获取数据集

创建数据集

删除数据集

导出数据集

在数据集上训练模型

项目 AP

列出项目

获取项目

创建项目

删除项目

模型 AP

列出模型

获取模型

上传模型

删除模型

下载模型

运行推理

训练 AP

开始训练

获取训练状态

取消训练

部署 AP

列出部署

创建部署

获取部署

启动部署

停止部署

删除部署

获取指标

获取日志

导出 AP

列出导出

创建导出

获取导出状态

活动 AP

列出活动

标记事件已读

归档事件

回收站 AP

列出回收站

恢复项目

清空回收站

账单 AP

获取余额

获取使用情况摘要

创建结账会话

创建订阅结账

创建门户会话

获取支付历史

存储 AP

获取存储信息

GDPR AP

导出/删除账户数据

AP 密钥 AP

列出 AP 密钥

创建 AP 密钥

删除 AP 密钥

错误代码

Python

安装与设置

身份验证

使用平台数据集

推送至平台

API示例

Webhooks

常见问题

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

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

是否有API客户端库？