Chuyển đến nội dung

REST API Thẩm quyền giải quyết

Nền tảng Ultralytics cung cấp một giải pháp toàn diện. REST API Để truy cập theo lập 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.

Hướng dẫn 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 cần xác thực thông qua khóa API.

Lấy khóa API

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

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

Tiêu đề ủy quyền

Hãy 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 đều sử dụng:

https://platform.ultralytics.com/api

Giới hạn tỷ lệ

Kế hoạchSố yêu cầu/phútSố lượng yê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 độ đượ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 ở định dạng 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ả
pagesố nguyênSố trang (mặc định: 1)
limitsố nguyênSố mục trên mỗi trang (mặc định: 20)
tasksợi dâyLọc theo loại nhiệm vụ

Phản ứng:

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

Thân hình:

{
    "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.

API dự án

Liệt kê các dự án

GET /api/projects

Nhận dự án

GET /api/projects/{projectId}

Tạo dự án

POST /api/projects

Thân hình:

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

Xóa Dự án

DELETE /api/projects/{projectId}

API mô hình

Liệt kê các mô hình

GET /api/models

Tham số truy vấn:

Tham sốLoạiMô tả
projectIdsợi dâyLọc theo dự án
tasksợi dâyLọc theo loại nhiệm vụ

Lấy mô hình

GET /api/models/{modelId}

Tải lên mô hình

POST /api/models

Biểu mẫu nhiều phần:

Cánh đồngLoạiMô tả
filetệpTệp mô hình .pt
projectIdsợi dâyDự án mục tiêu
namesợi dâyTên mẫu

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 đã được ký cho các tệp mô hình.

Chạy suy luận

POST /api/models/{modelId}/predict

Biểu mẫu nhiều phần:

Cánh đồngLoạiMô tả
filetệpTệp hình ảnh
conftrôi nổiNgưỡng tin cậy
ioutrôi nổiIoU ngưỡng

Phản ứng:

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

API đào tạo

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

POST /api/training/start

Thân hình:

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

Nhận trạng thái đào tạo

GET /api/models/{modelId}/training

Hủy bỏ khóa đào tạo

DELETE /api/models/{modelId}/training

API triển khai

Liệt kê các triển khai

GET /api/deployments

Tham số truy vấn:

Tham sốLoạiMô tả
modelIdsợi dâyLọc theo mẫu

Tạo triển khai

POST /api/deployments

Thân hình:

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

Nhận 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 số liệu

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ả
severitysợi dâyTHÔNG TIN, CẢNH BÁO, LỖI
limitsố nguyênSố lượng mục nhập

API xuất khẩu

Danh sách xuất khẩu

GET /api/exports

Tạo xuất khẩu

POST /api/exports

Thân hình:

{
    "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 khẩu

GET /api/exports/{exportId}

API hoạt động

Theo dõi 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ả
startDatesợi dâyLọc theo ngày (ISO)
endDatesợi dâyLọc theo ngày (ISO)
searchsợi dâyTìm kiếm trong tin nhắn sự kiện

Đánh dấu các sự kiện đã thấy

POST /api/activity/mark-seen

Sự kiện lưu trữ

POST /api/activity/archive

API thùng rác

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

Danh sách Thùng rác

GET /api/trash

Khôi phục mục

POST /api/trash

Thân hình:

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

Đổ 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ý số dư tín dụng và các gói đăng ký.

Tìm sự cân bằng

GET /api/billing/balance

Phản ứng:

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

Đô la Mỹ siêu nhỏ

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

Nhận bản tóm tắt sử dụng

GET /api/billing/usage-summary

Trả lại thông tin chi tiết về gói cước, giới hạn và số liệu sử dụng.

Tạo phiên thanh toán

POST /api/billing/checkout-session

Thân hình:

{
    "amount": 25
}

Tạo phiên thanh toán Stripe cho giao dịch mua bằng thẻ tín dụng (từ 5$ đến 1000$).

Tạo trang 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ý đăng ký.

Xem 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 về dung lượng lưu trữ

GET /api/storage

Phản ứng:

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

API GDPR

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

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

POST /api/gdpr

Thân hình:

{
    "action": "export"
}
Hoạt độ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.

Khóa API API

Liệt kê các khóa API

GET /api/api-keys

Tạo khóa API

POST /api/api-keys

Thân hình:

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

Xóa khóa API

DELETE /api/api-keys/{keyId}

Mã lỗi

Mã sốMô tả
UNAUTHORIZEDKhóa API không hợp lệ hoặc bị thiếu
FORBIDDENQuyền hạn không đủ
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ủ

Hỗ trợ SDK

Để tích hợp dễ dàng hơn, hãy sử dụng Ultralytics Python bưu kiện.

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

Việc tích hợp nền tảng yêu cầu ultralytics bản >= 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.

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

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

Sự kiệnMô tả
training.startedCông việc đào tạo đã bắt đầu
training.epochKỷ nguyên đã hoàn thành
training.completedBuổi huấn luyện đã kết thúc.
training.failedQuá trình huấn luyện thất bại
export.completedSẵn sàng xuất khẩu

Tính nă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ả tìm kiếm 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?

Đúng vậy, tất cả các chức năng đều có sẵn thông qua REST. SDK chỉ là một lớp bao bọc tiện lợi.

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

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

Tôi nên xử lý giới hạn số lượt truy cập như thế nào?

Thực hiện backoff theo cấp số nhân:

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 0 ngày trước ✏️ Được cập nhật 0 ngày trước
glenn-jocher

Bình luận