跳转至内容

REST API

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

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

请参阅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

速率限制

计划请求/分钟请求/天
免费601,000
Pro30050,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": { ... }
  }
}

数据集 API

列出数据集

GET /api/datasets

查询参数：

参数类型描述
pageint页码（默认：1）
limitint每页项目数（默认：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。

项目 API

项目列表

GET /api/projects

获取项目

GET /api/projects/{projectId}

创建项目

POST /api/projects

正文：

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

删除项目

DELETE /api/projects/{projectId}

模型 API

列表模型

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

训练API

开始训练

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

部署 API

列出部署

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字符串信息, 警告, 错误
limitint条目数量

导出API

列表导出

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}

活动API

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

列活动

GET /api/activity

查询参数：

参数类型描述
startDate字符串按日期筛选（ISO）
endDate字符串筛选至日期（ISO）
search字符串在事件消息中搜索

标记已查看事件

POST /api/activity/mark-seen

存档活动

POST /api/activity/archive

垃圾API

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

垃圾列表

GET /api/trash

恢复项目

POST /api/trash

正文：

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

清空垃圾桶

POST /api/trash/empty

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

计费API

管理积分和订阅。

保持平衡

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
}

创建一个Stripe结账会话，用于信用卡购买（金额范围：5美元至1000美元）。

创建订阅结账

POST /api/billing/subscription-checkout

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

创建门户会话

POST /api/billing/portal-session

返回订阅管理所需的Stripe计费门户网址。

获取付款记录

GET /api/billing/payments

返回来自Stripe的支付交易列表。

存储API

获取存储信息

GET /api/storage

回应：

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

GDPR API

符合GDPR的数据导出与删除端点。

导出/删除账户数据

POST /api/gdpr

正文：

{
    "action": "export"
}
行动描述
export下载所有账户数据
delete删除账户及所有数据

不可逆转的行动

账户删除操作不可逆，所有数据、模型和部署都将被永久删除。

API密钥 API

列出 API 密钥

GET /api/api-keys

创建 API 密钥

POST /api/api-keys

正文：

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

删除API密钥

DELETE /api/api-keys/{keyId}

错误代码

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

SDK支持

为便于集成，请Ultralytics Python 。

软件包版本要求

平台集成需要ultralytics>= 8.4.0 版本。较低版本将无法与平台兼容。

pip install "ultralytics>=8.4.0"

import os

from ultralytics import YOLO

# Set API key
os.environ["ULTRALYTICS_API_KEY"] = "ul_your_key"

# Train with Platform integration
model = YOLO("yolo11n.pt")
model.train(data="ul://username/datasets/my-dataset", project="username/my-project", name="experiment-1", epochs=100)

网络钩子

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


📅 0 天前创建 ✏️ 0 天前更新
glenn-jocher

评论