Chuyển đến nội dung

Tài liệu tham khảo REST API

Nền tảng Ultralytics cung cấp một REST API toàn diện để truy cập theo chương trình vào các tập dữ liệu, mô hình, quá trình huấn luyện và triển khai.

Bắt đầu nhanh

# 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

Xác thực

Tất cả các yêu cầu API đều yêu cầu xác thực bằng khóa API.

Lấy Khóa API

  1. Truy cập Cài đặt > Khóa API
  2. Nhấp vào Tạo Khóa
  3. Sao chép khóa đã tạo

Xem Khóa API để biết hướng dẫn chi tiết.

Tiêu đề ủy quyền

Bao gồm khóa API của bạn trong tất cả các yêu cầu:

Authorization: Bearer ul_your_api_key_here

Ví dụ

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

URL cơ sở

Tất cả các điểm cuối API sử dụng:

https://platform.ultralytics.com/api

Giới hạn tốc độ

GóiYêu cầu/PhútYêu cầu/Ngày
Miễn phí601,000
Pro30050,000
Doanh nghiệpTùy chỉnhTùy chỉnh

Các tiêu đề giới hạn tốc độ yêu cầu được bao gồm trong phản hồi:

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

Định dạng phản hồi

Tất cả các phản hồi đều là JSON:

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

Phản hồi lỗi

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

API Tập dữ liệu

Liệt kê bộ dữ liệu

GET /api/datasets

Tham số truy vấn:

Tham sốLoạiMô tả
pageintSố trang (mặc định: 1)
limitintSố mục trên mỗi trang (mặc định: 20)
taskchuỗiLọc theo loại tác vụ

Phản hồi:

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

Lấy Tập dữ liệu

GET /api/datasets/{datasetId}

Tạo Tập dữ liệu

POST /api/datasets

Nội dung:

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

Xóa bộ dữ liệu

DELETE /api/datasets/{datasetId}

Xuất Tập dữ liệu

POST /api/datasets/{datasetId}/export

Trả về URL tải xuống định dạng NDJSON.

Huấn luyện mô hình trên tập dữ liệu

GET /api/datasets/{datasetId}/models

Trả về danh sách các mô hình được huấn luyện bằng tập dữ liệu này, thể hiện mối quan hệ giữa các tập dữ liệu và các mô hình mà chúng tạo ra.

Phản hồi:

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

API Dự án

Liệt kê Dự án

GET /api/projects

Lấy Dự án

GET /api/projects/{projectId}

Tạo dự án

POST /api/projects

Nội dung:

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

Xóa Dự án

DELETE /api/projects/{projectId}

API Mô hình

Liệt kê Mô hình

GET /api/models

Tham số truy vấn:

Tham sốLoạiMô tả
projectIdchuỗiLọc theo dự án
taskchuỗiLọc theo loại tác vụ

Lấy Mô hình

GET /api/models/{modelId}

Tải lên mô hình

POST /api/models

Biểu mẫu đa phần:

TrườngLoạiMô tả
filetệpTệp .pt của mô hình
projectIdchuỗiDự án đích
namechuỗiTên mô hình

Xóa mô hình

DELETE /api/models/{modelId}

Tải xuống Mô hình

GET /api/models/{modelId}/files

Trả về các URL tải xuống đã ký cho các tệp mô hình.

Chạy suy luận

POST /api/models/{modelId}/predict

Biểu mẫu đa phần:

TrườngLoạiMô tả
filetệpTệp hình ảnh
confsố thựcNgưỡng tin cậy
iousố thựcNgưỡng IoU

Phản hồi:

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

API Huấn luyện

Bắt Đầu Huấn Luyện

POST /api/training/start

Nội dung:

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

Lấy Trạng thái Huấn luyện

GET /api/models/{modelId}/training

Hủy Huấn luyện

DELETE /api/models/{modelId}/training

AP Triển khai

Liệt kê Triển khai

GET /api/deployments

Tham số truy vấn:

Tham sốLoạiMô tả
modelIdchuỗiLọc theo mô hình

Tạo Triển khai

POST /api/deployments

Nội dung:

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

Lấy Triển khai

GET /api/deployments/{deploymentId}

Bắt đầu Triển khai

POST /api/deployments/{deploymentId}/start

Dừng Triển khai

POST /api/deployments/{deploymentId}/stop

Xóa Triển khai

DELETE /api/deployments/{deploymentId}

Lấy Chỉ số

GET /api/deployments/{deploymentId}/metrics

Lấy Nhật ký

GET /api/deployments/{deploymentId}/logs

Tham số truy vấn:

Tham sốLoạiMô tả
severitychuỗiTHÔNG TIN, CẢNH BÁO, LỖI
limitintSố lượng mục nhập

AP Xuất

Liệt kê Xuất

GET /api/exports

Tạo Xuất

POST /api/exports

Nội dung:

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

Các định dạng được hỗ trợ:

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

Lấy Trạng thái Xuất

GET /api/exports/{exportId}

AP Hoạt động

track và quản lý các sự kiện hoạt động cho tài khoản của bạn.

Liệt kê Hoạt động

GET /api/activity

Tham số truy vấn:

Tham sốLoạiMô tả
startDatechuỗiLọc từ ngày (ISO)
endDatechuỗiLọc đến ngày (ISO)
searchchuỗiTìm kiếm trong thông báo sự kiện

Đánh dấu Sự kiện đã xem

POST /api/activity/mark-seen

Lưu trữ Sự kiện

POST /api/activity/archive

AP Thùng rác

Quản lý các tài nguyên đã xóa mềm (lưu giữ 30 ngày).

Liệt kê Thùng rác

GET /api/trash

Khôi phục Mục

POST /api/trash

Nội dung:

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

Làm rỗng Thùng rác

POST /api/trash/empty

Xóa vĩnh viễn tất cả các mục trong thùng rác.

API Thanh toán

Quản lý tín dụng và gói đăng ký.

Lấy Số dư

GET /api/billing/balance

Phản hồi:

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

Micro-USD

Tất cả các khoản tiền được tính bằng micro-USD (1.000.000 = 1,00 USD) để đảm bảo tính toán chính xác.

Lấy Tóm tắt Sử dụng

GET /api/billing/usage-summary

Trả về chi tiết gói, giới hạn và các chỉ số sử dụng.

Tạo Phiên thanh toán

POST /api/billing/checkout-session

Nội dung:

{
    "amount": 25
}

Tạo phiên thanh toán Stripe để mua tín dụng (5-1000 USD).

Tạo Thanh toán Đăng ký

POST /api/billing/subscription-checkout

Tạo phiên thanh toán Stripe cho gói đăng ký Pro.

Tạo Phiên Cổng thông tin

POST /api/billing/portal-session

Trả về URL đến cổng thanh toán Stripe để quản lý gói đăng ký.

Lấy Lịch sử Thanh toán

GET /api/billing/payments

Trả về danh sách các giao dịch thanh toán từ Stripe.

API Lưu trữ

Lấy thông tin lưu trữ

GET /api/storage

Phản hồi:

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

API GDPR

Các điểm cuối tuân thủ GDPR để xuất và xóa dữ liệu.

Xuất/Xóa dữ liệu tài khoản

POST /api/gdpr

Nội dung:

{
    "action": "export"
}
Hành độngMô tả
exportTải xuống tất cả dữ liệu tài khoản
deleteXóa tài khoản và tất cả dữ liệu

Hành động không thể đảo ngược

Việc xóa tài khoản là vĩnh viễn và không thể hoàn tác. Tất cả dữ liệu, mô hình và triển khai sẽ bị xóa.

API Khóa API

Liệt kê khóa API

GET /api/api-keys

Tạo khóa API

POST /api/api-keys

Nội dung:

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

Xóa khóa API

DELETE /api/api-keys/{keyId}

Mã lỗi

MãMô tả
UNAUTHORIZEDKhóa API không hợp lệ hoặc bị thiếu
FORBIDDENKhông đủ quyền
NOT_FOUNDKhông tìm thấy tài nguyên
VALIDATION_ERRORDữ liệu yêu cầu không hợp lệ
RATE_LIMITEDQuá nhiều yêu cầu
INTERNAL_ERRORLỗi máy chủ

Python Tích hợp

Để tích hợp dễ dàng hơn, hãy sử dụng gói Ultralytics python.

Cài đặt & Thiết lập

pip install ultralytics

Xác minh cài đặt:

yolo check

Yêu cầu phiên bản gói

Tích hợp Nền tảng yêu cầu ultralytics>=8.4.0. Các phiên bản thấp hơn sẽ KHÔNG hoạt động với Nền tảng.

Xác thực

Phương pháp 1: CLI Cấu hình (Khuyến nghị)

yolo settings api_key=YOUR_API_KEY

Phương pháp 2: Biến môi trường

export ULTRALYTICS_API_KEY=YOUR_API_KEY

Phương pháp 3: Trong mã lập trình

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Sử dụng tập dữ liệu nền tảng

Bộ dữ liệu tham chiếu với ul:// URI:

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

Định dạng 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

Đẩy lên nền tảng

Gửi kết quả đến dự án Nền tảng:

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

Những gì được đồng bộ hóa:

  • Số liệu huấn luyện (thời gian thực)
  • Trọng lượng mô hình cuối cùng
  • Biểu đồ xác thực
  • Đầu ra bảng điều khiển
  • Số liệu hệ thống

Ví dụ về API

Tải mô hình từ Nền tảng:

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

Chạy suy luận:

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

Mô hình xuất khẩu:

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

Validation (Kiểm định):

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

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

Webhooks

Webhook thông báo cho máy chủ của bạn về các sự kiện của Nền tảng:

Sự kiệnMô tả
training.startedCông việc huấn luyện đã bắt đầu
training.epochEpoch đã hoàn thành
training.completedHuấn luyện đã hoàn tất
training.failedHuấn luyện thất bại
export.completedXuất đã sẵn sàng

Thiết lập Webhook có sẵn trong các gói Enterprise.

Câu hỏi thường gặp

Làm thế nào để phân trang kết quả lớn?

Sử dụng page và limit tham số:

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

Tôi có thể sử dụng API mà không cần SDK không?

Có, tất cả chức năng đều có sẵn thông qua REST. SDK là một trình bao bọc tiện lợi.

Có thư viện client API nào không?

Hiện tại, hãy sử dụng gói Ultralytics python hoặc thực hiện các yêu cầu HTTP trực tiếp. Các thư viện client chính thức cho các ngôn ngữ khác đang được lên kế hoạch.

Làm thế nào để xử lý giới hạn tốc độ yêu cầu?

Triển khai exponential backoff:

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


📅 Được tạo 20 ngày trước ✏️ Cập nhật 14 ngày trước
glenn-jocherLaughing-q

Bình luận