Tham chiếu REST API

Ultralytics Platform cung cấp một REST API toàn diện để truy cập theo lập trình vào các tập dữ liệu, model, quá trình huấn luyện và triển khai.

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

Tổng quan về API

API được tổ chức xoay quanh các tài nguyên cốt lõi của nền tảng:

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

Xác thực

Các API tài nguyên như datasets, projects, models, training, exports và predictions sử dụng xác thực bằng API-key. Các endpoint công khai (liệt kê datasets, projects và models công khai) hỗ trợ quyền đọc ẩn danh mà không cần key. Các lộ trình liên quan đến tài khoản — bao gồm hoạt động, cài đặt, teams, billing và các luồng GDPR — hiện yêu cầu một phiên trình duyệt đã xác thực và không khả dụng thông qua API key.

Lấy API Key

1. Đi tới Settings > API Keys
2. Nhấp vào Create Key
3. Sao chép key đã được tạo

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

Header ủy quyền

Thêm API key của bạn vào tất cả các request:

Authorization: Bearer YOUR_API_KEY

Ví dụ

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

Base URL

Tất cả các endpoint API đều sử dụng:

Giới hạn tốc độ (Rate Limits)

API áp dụng giới hạn tốc độ cho mỗi API-key (cửa sổ trượt, được hỗ trợ bởi Upstash Redis) để bảo vệ chống lại việc lạm dụng trong khi vẫn giữ cho việc sử dụng hợp pháp không bị hạn chế. Lưu lượng truy cập ẩn danh được bảo vệ bổ sung bởi các biện pháp kiểm soát lạm dụng cấp nền tảng của Vercel.

Khi bị điều tiết, API sẽ trả về 429 cùng với metadata thử lại:

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

Giới hạn theo API Key

Giới hạn tốc độ được áp dụng tự động dựa trên endpoint đang được gọi. Các thao tác tiêu tốn tài nguyên có giới hạn chặt chẽ hơn để ngăn chặn lạm dụng, trong khi các thao tác CRUD tiêu chuẩn chia sẻ một mức giới hạn mặc định hào phóng:

Mỗi danh mục có một bộ đếm độc lập cho mỗi API key. Ví dụ, việc thực hiện 20 request dự đoán không ảnh hưởng đến hạn mức mặc định 100 request/phút của bạn.

Dedicated Endpoints (Không giới hạn)

Dedicated endpoints không chịu các giới hạn tốc độ của API key. Khi bạn triển khai một model đến một dedicated endpoint, các request tới URL endpoint đó (ví dụ: https://predict-abc123.run.app/predict) đi trực tiếp đến dịch vụ chuyên dụng của bạn mà không có giới hạn tốc độ từ Nền tảng. Bạn đang trả tiền cho điện toán, vì vậy bạn nhận được thông lượng từ cấu hình dịch vụ chuyên dụng của mình thay vì các giới hạn API chia sẻ.

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

Phản hồi thành công

Các phản hồi trả về JSON với các trường đặc thù của tài nguyên:

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

Phản hồi lỗi

{
    "error": "Dataset not found"
}

Datasets API

Tạo, duyệt và quản lý các tập dữ liệu hình ảnh được gán nhãn để huấn luyện các model YOLO. Xem Tài liệu Datasets.

Liệt kê các tập dữ liệu

GET /api/datasets

Các tham số truy vấn:

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

Phản hồi:

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

Lấy tập dữ liệu

GET /api/datasets/{datasetId}

Trả về chi tiết đầy đủ của tập dữ liệu bao gồm metadata, tên lớp và số lượng chia tách dữ liệu.

Tạo tập dữ liệu

POST /api/datasets

Body:

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

Cập nhật tập dữ liệu

PATCH /api/datasets/{datasetId}

Body (cập nhật một phần):

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

Xóa tập dữ liệu

DELETE /api/datasets/{datasetId}

Xóa mềm tập dữ liệu (được chuyển vào thùng rác, có thể khôi phục trong vòng 30 ngày).

Sao chép tập dữ liệu

POST /api/datasets/{datasetId}/clone

Tạo bản sao của tập dữ liệu với tất cả hình ảnh và nhãn. Chỉ các tập dữ liệu công khai mới có thể được sao chép. Yêu cầu một phiên trình duyệt nền tảng đang hoạt động — không khả dụng qua API key.

Body (tất cả các trường đều tùy chọn):

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

Xuất tập dữ liệu

GET /api/datasets/{datasetId}/export

Trả về phản hồi JSON với URL tải xuống đã ký cho bản xuất tập dữ liệu mới nhất.

Các tham số truy vấn:

Phản hồi:

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

Tạo phiên bản tập dữ liệu

POST /api/datasets/{datasetId}/export

Tạo một bản snapshot phiên bản mới được đánh số của tập dữ liệu. Chỉ dành cho chủ sở hữu. Phiên bản này ghi lại số lượng hình ảnh hiện tại, số lượng lớp, số lượng chú thích và phân bổ tách dữ liệu, sau đó tạo và lưu trữ một bản xuất NDJSON không thể thay đổi.

Request Body:

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

Tất cả các trường đều tùy chọn. Trường description là nhãn do người dùng cung cấp cho phiên bản.

Phản hồi:

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

Cập nhật mô tả phiên bản

PATCH /api/datasets/{datasetId}/export

Cập nhật mô tả của một phiên bản hiện có. Chỉ dành cho chủ sở hữu.

Request Body:

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

Phản hồi:

{
    "ok": true
}

Lấy thống kê lớp

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

Trả về phân bổ lớp, bản đồ nhiệt vị trí và thống kê kích thước. Kết quả được lưu cache tối đa 5 phút.

Phản hồi:

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

Lấy các model được huấn luyện trên tập dữ liệu

GET /api/datasets/{datasetId}/models

Trả về các model đã được huấn luyện sử dụng tập dữ liệu này.

Phản hồi:

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

Tự động chú thích tập dữ liệu

POST /api/datasets/{datasetId}/predict

Chạy suy luận YOLO trên hình ảnh tập dữ liệu để tự động tạo chú thích. Sử dụng một model đã chọn để dự đoán nhãn cho các hình ảnh chưa được chú thích.

Body:

Nhập tập dữ liệu

POST /api/datasets/ingest

Tạo công việc nhập tập dữ liệu để xử lý các tệp ZIP hoặc TAR đã tải lên, bao gồm .tar.gz và .tgz, chứa hình ảnh và nhãn.

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]

Hình ảnh tập dữ liệu

Liệt kê hình ảnh

GET /api/datasets/{datasetId}/images

Các tham số truy vấn:

Lấy URL hình ảnh đã ký

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

Lấy các URL đã ký cho một loạt các hash hình ảnh (để hiển thị trên trình duyệt).

Xóa hình ảnh

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

Lấy nhãn hình ảnh

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

Trả về các chú thích và tên lớp cho một hình ảnh cụ thể.

Cập nhật nhãn hình ảnh

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

Body:

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

Thao tác hình ảnh hàng loạt

Di chuyển hình ảnh giữa các split (train/val/test) trong một tập dữ liệu:

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

Xóa hình ảnh hàng loạt:

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

API Dự án

Tổ chức các model của bạn vào các dự án. Mỗi model thuộc về một dự án. Xem Tài liệu dự án.

Liệt kê dự án

GET /api/projects

Các tham số truy vấn:

Lấy dự án

GET /api/projects/{projectId}

Tạo dự án

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

Cập nhật dự án

PATCH /api/projects/{projectId}

Xóa dự án

DELETE /api/projects/{projectId}

Xóa mềm dự án (được chuyển vào thùng rác).

Sao chép dự án

POST /api/projects/{projectId}/clone

Sao chép một dự án công khai (cùng với tất cả các model của dự án đó) vào không gian làm việc của bạn. Yêu cầu một phiên trình duyệt nền tảng đang hoạt động — không khả dụng qua API key.

Biểu tượng dự án

Tải lên biểu tượng dự án (multipart form với tệp hình ảnh):

POST /api/projects/{projectId}/icon

Xóa biểu tượng dự án:

DELETE /api/projects/{projectId}/icon

Cả hai đều yêu cầu một phiên trình duyệt nền tảng đang hoạt động — không khả dụng qua API key.

API Mô hình

Quản lý các model YOLO đã được huấn luyện — xem số liệu, tải xuống trọng số, chạy suy luận và xuất sang các định dạng khác. Xem tài liệu về Model.

Liệt kê Model

GET /api/models

Các tham số truy vấn:

Liệt kê các Model đã hoàn thành

GET /api/models/completed

Trả về các model đã huấn luyện xong (để sử dụng trong các trình chọn model và triển khai).

Lấy Model

GET /api/models/{modelId}

Tạo Model

POST /api/models

JSON Body:

Cập nhật Model

PATCH /api/models/{modelId}

Xóa Model

DELETE /api/models/{modelId}

Tải xuống các tệp Model

GET /api/models/{modelId}/files

Trả về các URL tải xuống đã được ký cho các tệp model.

Sao chép mô hình

POST /api/models/{modelId}/clone

Sao chép một model công khai vào một trong các dự án của bạn. Yêu cầu một phiên trình duyệt nền tảng đang hoạt động — không khả dụng qua API key.

Body:

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

Theo dõi lượt tải xuống

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

Theo dõi phân tích lượt tải xuống model.

Chạy suy luận

POST /api/models/{modelId}/predict

Multipart Form:

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

Phản hồi:

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

Lấy Predict Token

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

Làm nóng (Warmup) Model

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

API Huấn luyện

Khởi chạy quá trình huấn luyện YOLO trên các GPU đám mây (24 loại GPU từ RTX 2000 Ada đến B300) và theo dõi tiến trình theo thời gian thực. Xem tài liệu về Huấn luyện trên Đám mây.

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]

Bắt đầu huấn luyện

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

Lấy trạng thái huấn luyện

GET /api/models/{modelId}/training

Trả về trạng thái công việc huấn luyện hiện tại, số liệu và tiến trình cho một model. Các dự án công khai có thể được truy cập ẩn danh; các dự án riêng tư yêu cầu phiên trình duyệt nền tảng đang hoạt động (tuyến đường này không chấp nhận xác thực bằng API key).

Hủy huấn luyện

DELETE /api/models/{modelId}/training

Chấm dứt instance tính toán đang chạy và đánh dấu công việc là đã hủy. Yêu cầu phiên trình duyệt nền tảng đang hoạt động — không khả dụng qua API key.

API Triển khai

Triển khai các model tới các điểm cuối suy luận chuyên dụng với các kiểm tra sức khỏe và giám sát. Các triển khai mới sử dụng scale-to-zero theo mặc định và API chấp nhận một đối tượng resources tùy chọn. Xem tài liệu về Endpoint.

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]

Liệt kê Triển khai

GET /api/deployments

Các tham số truy vấn:

Tạo Triển khai

POST /api/deployments

Body:

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

Tạo một điểm cuối suy luận chuyên dụng trong khu vực được chỉ định. Điểm cuối có thể truy cập toàn cầu thông qua một URL duy nhất.

Lấy Triển khai

GET /api/deployments/{deploymentId}

Xóa Triển khai

DELETE /api/deployments/{deploymentId}

Bắt đầu Triển khai

POST /api/deployments/{deploymentId}/start

Tiếp tục một triển khai đã dừng.

Dừng Triển khai

POST /api/deployments/{deploymentId}/stop

Tạm dừng một triển khai đang chạy (dừng thanh toán).

Kiểm tra sức khỏe

GET /api/deployments/{deploymentId}/health

Trả về trạng thái sức khỏe của điểm cuối triển khai.

Chạy suy luận trên Triển khai

POST /api/deployments/{deploymentId}/predict

Gửi hình ảnh trực tiếp đến một điểm cuối triển khai để suy luận. Về mặt chức năng tương đương với dự đoán model, nhưng được định tuyến qua điểm cuối chuyên dụng để có độ trễ thấp hơn.

Multipart Form:

Lấy số liệu

GET /api/deployments/{deploymentId}/metrics

Trả về số liệu đếm yêu cầu, độ trễ và tỷ lệ lỗi với dữ liệu sparkline.

Các tham số truy vấn:

Lấy Logs

GET /api/deployments/{deploymentId}/logs

Các tham số truy vấn:

API giám sát

Chỉ số tổng hợp

GET /api/monitoring

Trả về các chỉ số tổng hợp trên tất cả các triển khai của người dùng: tổng số yêu cầu, số triển khai đang hoạt động, tỷ lệ lỗi và độ trễ trung bình.

API xuất (Export API)

Chuyển đổi model sang các định dạng được tối ưu hóa như ONNX, TensorRT, CoreML và TFLite để triển khai trên thiết bị biên (edge). Xem Tài liệu triển khai.

Danh sách xuất

GET /api/exports

Các tham số truy vấn:

Tạo yêu cầu xuất

POST /api/exports

Body:

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

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

Lấy trạng thái xuất

GET /api/exports/{exportId}

Hủy yêu cầu xuất

DELETE /api/exports/{exportId}

Theo dõi quá trình tải xuống xuất

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

API hoạt động (Activity API)

Xem nguồn cấp dữ liệu về các hành động gần đây trên tài khoản của bạn — các lượt huấn luyện, tải lên, v.v. Xem Tài liệu hoạt động.

Danh sách hoạt động

GET /api/activity

Các tham số truy vấn:

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

POST /api/activity/mark-seen

Body:

{
    "all": true
}

Hoặc truyền vào các ID cụ thể:

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

Lưu trữ sự kiện

POST /api/activity/archive

Body:

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

Hoặc truyền vào các ID cụ thể:

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

API thùng rác

Xem và khôi phục các mục đã xóa. Các mục sẽ bị xóa vĩnh viễn sau 30 ngày. Xem Tài liệu thùng rác.

Danh sách thùng rác

GET /api/trash

Các tham số truy vấn:

Khôi phục mục

POST /api/trash

Body:

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

Xóa vĩnh viễn mục

DELETE /api/trash

Body:

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

Dọn sạch thùng rác

DELETE /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

Kiểm tra số dư tín dụng, mua tín dụng, xem lịch sử giao dịch và cấu hình tự động nạp tiền. Xem Tài liệu thanh toán.

Lấy số dư

GET /api/billing/balance

Các tham số truy vấn:

Phản hồi:

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

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.

Lấy các giao dịch

GET /api/billing/transactions

Trả về lịch sử giao dịch (mới nhất trước).

Các tham số truy vấn:

Tạo phiên thanh toán (Checkout Session)

POST /api/billing/checkout-session

Body:

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

Tạo một phiên thanh toán để mua tín dụng.

Tạo phiên thanh toán đăng ký

POST /api/billing/subscription-checkout

Tạo một phiên thanh toán để nâng cấp gói đăng ký Pro.

Body:

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

Hủy hoặc Tiếp tục Đăng ký

DELETE /api/billing/subscription-checkout

Theo mặc định, hủy đăng ký Pro vào cuối kỳ. Gửi {"resume": true} để tiếp tục một yêu cầu hủy đã được lên lịch trước khi kỳ thanh toán kết thúc.

Body:

{
    "resume": true
}

Tự động nạp tiền

Tự động thêm tín dụng khi số dư giảm xuống dưới ngưỡng.

Lấy Cấu hình Tự động Nạp tiền

GET /api/billing/auto-topup

Các tham số truy vấn:

Cập nhật Cấu hình Tự động Nạp tiền

PATCH /api/billing/auto-topup

Body:

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

Phương thức Thanh toán

Liệt kê các Phương thức Thanh toán

GET /api/billing/payment-methods

Tạo Setup Intent

POST /api/billing/payment-methods/setup

Trả về một client secret để thêm phương thức thanh toán mới.

Đặt Phương thức Thanh toán Mặc định

POST /api/billing/payment-methods/default

Body:

{
    "paymentMethodId": "pm_123"
}

Cập nhật Thông tin Thanh toán

PATCH /api/billing/payment-methods

Body:

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

Xóa Phương thức Thanh toán

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

API Lưu trữ

Kiểm tra phân tích mức sử dụng lưu trữ theo danh mục (tập dữ liệu, model, bản xuất) và xem các mục lớn nhất của bạn.

Lấy Thông tin Lưu trữ

GET /api/storage

Phản hồi:

{
    "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 Tải lên

Tải tệp trực tiếp lên bộ lưu trữ đám mây bằng các URL đã ký để truyền tải nhanh chóng và đáng tin cậy. Sử dụng quy trình hai bước: lấy URL đã ký, sau đó tải tệp lên. Xem tài liệu về Dữ liệu.

Lấy URL Tải lên đã Ký

POST /api/upload/signed-url

Yêu cầu một URL đã ký để tải tệp trực tiếp lên bộ lưu trữ đám mây. URL đã ký bỏ qua máy chủ API để truyền các tệp lớn.

Body:

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

Phản hồi:

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

Hoàn tất Tải lên

POST /api/upload/complete

Thông báo cho nền tảng rằng quá trình tải tệp lên đã hoàn tất để bắt đầu xử lý.

Body:

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

API Khóa API

Quản lý các API key của bạn để truy cập theo lập trình. Xem tài liệu về API Keys.

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

GET /api/api-keys

Tạo Khóa API

POST /api/api-keys

Body:

{
    "name": "training-server"
}

Xóa Khóa API

DELETE /api/api-keys

Các tham số truy vấn:

Ví dụ:

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

API Nhóm & Thành viên

Tạo không gian làm việc nhóm, mời thành viên và quản lý vai trò để cộng tác. Xem tài liệu về Nhóm.

Liệt kê các Nhóm

GET /api/teams

Tạo Nhóm

POST /api/teams/create

Body:

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

Liệt kê Thành viên

GET /api/members

Trả về các thành viên của không gian làm việc hiện tại.

Mời Thành viên

POST /api/members

Body:

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

Cập nhật Vai trò Thành viên

PATCH /api/members/{userId}

Xóa Thành viên

DELETE /api/members/{userId}

Chuyển giao Quyền sở hữu

POST /api/members/transfer-ownership

Lời mời

Chấp nhận Lời mời

POST /api/invites/accept

Lấy Thông tin Lời mời

GET /api/invites/info

Các tham số truy vấn:

Thu hồi Lời mời

DELETE /api/invites/{inviteId}

Gửi lại Lời mời

POST /api/invites/{inviteId}/resend

API Khám phá

Tìm kiếm và duyệt các tập dữ liệu công khai và dự án được cộng đồng chia sẻ. Xem tài liệu về Khám phá.

Tìm kiếm Nội dung Công khai

GET /api/explore/search

Các tham số truy vấn:

Dữ liệu thanh bên

GET /api/explore/sidebar

Trả về nội dung được tuyển chọn cho thanh bên Khám phá.

API Người dùng & Cài đặt

Quản lý hồ sơ, API key, mức sử dụng lưu trữ và cài đặt quyền riêng tư dữ liệu của bạn. Xem tài liệu về Cài đặt.

Lấy Người dùng theo Tên người dùng

GET /api/users

Các tham số truy vấn:

Theo dõi hoặc Bỏ theo dõi Người dùng

PATCH /api/users

Body:

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

Kiểm tra sự sẵn có của Tên người dùng

GET /api/username/check

Các tham số truy vấn:

Cài đặt

GET /api/settings
POST /api/settings

Lấy hoặc cập nhật cài đặt hồ sơ người dùng (tên hiển thị, tiểu sử, liên kết xã hội, v.v.).

Biểu tượng Hồ sơ

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

Tải lên hoặc xóa ảnh đại diện hồ sơ.

Onboarding

POST /api/onboarding

Hoàn tất quy trình onboarding (thiết lập vùng dữ liệu, tên người dùng).

API GDPR

Yêu cầu xuất tất cả dữ liệu của bạn hoặc xóa vĩnh viễn tài khoản của bạn. Xem tài liệu về Cài đặt.

Lấy Trạng thái Công việc GDPR

GET /api/gdpr

Các tham số truy vấn:

Trả về trạng thái công việc. Đối với các công việc xuất dữ liệu đã hoàn tất, phản hồi bao gồm downloadUrl.

Bắt đầu Quy trình Xuất hoặc Xóa

POST /api/gdpr

Body:

{
    "action": "export"
}

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

Tùy chọn cho không gian làm việc nhóm:

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

Mã lỗi

Tích hợp Python

Để tích hợp dễ dàng hơn, hãy sử dụng gói Python của Ultralytics, gói này tự động xử lý xác thực, tải lên và truyền phát số liệu theo thời gian thực.

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

pip install ultralytics

Xác minh cài đặt:

yolo check

Xác thực

yolo settings api_key=YOUR_API_KEY

Sử dụng Datasets của Nền tảng

Tham chiếu tập dữ liệu với URI ul://:

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

Định dạng URI:

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

Gửi kết quả đến một dự án trên nền tảng:

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

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

• Số liệu huấn luyện (thời gian thực)
• Trọng số model cuối cùng
• Biểu đồ xác thực
• Đầu ra console
• Số liệu hệ thống

Ví dụ về API

Tải model 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

Xuất model:

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

Xác thực:

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

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

Webhook

Nền tảng sử dụng các webhook nội bộ để truyền phát số liệu huấn luyện thời gian thực từ SDK Python ultralytics (chạy trên GPU đám mây hoặc máy từ xa/cục bộ) ngược lại nền tảng — bao gồm loss theo từng epoch, mAP, số liệu thống kê hệ thống và trạng thái hoàn thành. Các webhook này được xác thực thông qua webhookSecret HMAC được cung cấp cho mỗi công việc huấn luyện và không dành cho các ứng dụng người dùng sử dụng.

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

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

Hầu hết các endpoint sử dụng tham số limit để kiểm soát số lượng kết quả được trả về cho mỗi yêu cầu:

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

Các endpoint Activity và Trash cũng hỗ trợ tham số page cho việc phân trang theo trang:

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

Endpoint Explore Search sử dụng offset thay vì page, với kích thước trang cố định là 20:

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

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 khả dụng thông qua REST. SDK Python là một trình bao bọc tiện lợi bổ sung các tính năng như truyền phát số liệu thời gian thực và tự động tải lên model. Bạn cũng có thể khám phá tương tác tất cả các endpoint tại platform.ultralytics.com/api/docs.

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

Hiện tại, hãy sử dụng gói Python của Ultralytics 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 độ (rate limit)?

Sử dụng header Retry-After từ phản hồi 429 để chờ đợi đúng khoảng thời gian cần thiết:

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

Làm thế nào để tìm ID model hoặc tập dữ liệu của tôi?

ID tài nguyên được trả về khi bạn tạo tài nguyên thông qua API. Bạn cũng có thể tìm thấy chúng trong URL của nền tảng:

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

Sử dụng các endpoint liệt kê để tìm kiếm theo tên hoặc lọc theo dự án.