Tham chiếu REST API#

Ultralytics Platform cung cấp REST API toàn diện để truy cập 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.

# 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 xung quanh các tài nguyên nền tảng cốt lõi:

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    A --> D[Models]:::proc
    A --> E[Deployments]:::proc
    B -->|train on| D
    C -->|contains| D
    D -->|deploy to| E
    D -->|export| F[Exports]:::proc
    B -->|auto-annotate| B

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

Xác thực#

Các Resource API sử dụng xác thực API-key, bao gồm quản lý lớp (class) tập dữ liệu và phân chia (split), nhân bản, huấn luyện, xuất dữ liệu, triển khai và các truy vấn tài khoản được hỗ trợ. Các endpoint công khai hỗ trợ truy cập ẩn danh nếu có lưu ý. Các lộ trình ứng dụng chỉ dành cho trình duyệt sẽ bị loại trừ.

Lấy API Key#

1. Chuyển đến Settings > API Keys
2. Nhấp Create Key
3. Sao chép key đã tạo

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

Tiêu đề ủy quyền (Authorization Header)#

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

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 API endpoint sử dụng:

https://platform.ultralytics.com/api

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

API áp dụng giới hạn cửa sổ trượt (sliding-window) được hỗ trợ bởi Upstash Redis cho mỗi API key. Mỗi tuyến đường (route) sử dụng danh mục tương ứng dưới đây.

Khi bị giới hạn tốc độ, API trả về 429 kèm theo siêu dữ liệu thử lại:

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

Giới hạn theo API Key#

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

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

Endpoint chuyên dụng (Không giới hạn)#

Các endpoint chuyên dụng không chịu giới hạn tốc độ Platform API-key khi bạn gọi trực tiếp URL của endpoint (ví dụ: https://predict-abc123.run.app/predict). Thông lượng khi đó phụ thuộc vào cấu hình dịch vụ đã triển khai.

Đị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ể cho từng 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 mô hình YOLO. Xem Tài liệu tập dữ liệu.

Liệt kê Datasets#

GET /api/datasets

Tham số truy vấn (Query Parameters):

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

Phản hồi (Response):

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

GET /api/datasets/{datasetId}

Trả về thông tin chi tiết về dataset bao gồm tên lớp, số lượng phân chia và các thuộc tính khác do Platform quản lý. Metadata tùy chỉnh được tải riêng từ endpoint metadata bên dưới.

Truyền username khi {datasetId} là một slug tập dữ liệu thay vì một ID.

Tạo Dataset#

POST /api/datasets

Body:

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

Phản hồi (Response):

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

Cập nhật Dataset#

PATCH /api/datasets/{datasetId}

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

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

Gửi một đối tượng metadata trống ({}) để xóa metadata tùy chỉnh. Đối tượng metadata đã tuần tự hóa bị giới hạn ở 500.000 ký tự và mỗi khóa cấp cao nhất bị giới hạn ở 128 ký tự.

Lấy Metadata của Dataset#

GET /api/datasets/{datasetId}/metadata

Trả về đối tượng metadata tùy chỉnh và tập hợp các cặp trường/giá trị do Ultralytics quản lý ở chế độ chỉ đọc đã được tuyển chọn. Metadata tùy chỉnh bị chủ đích bỏ qua khỏi các payload dataset thông thường. Cần phải xác thực và có quyền truy cập workspace của dataset.

Biểu tượng tập dữ liệu#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

Tải lên một biểu tượng WebP có kích thước tối đa 5 MB dưới dạng trường form multipart image, hoặc xóa biểu tượng hiện tại.

Xóa Dataset#

DELETE /api/datasets/{datasetId}

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

Sao chép (Clone) Dataset#

POST /api/datasets/{datasetId}/clone

Tạo một bản sao của tập dữ liệu công khai, do bạn sở hữu hoặc tập dữ liệu không gian làm việc có thể chỉnh sửa, cùng với tất cả hình ảnh và nhãn.

Phần thân tùy chọn (tất cả các trường đều là tùy chọn):

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

Xuất Dataset#

GET /api/datasets/{datasetId}/export

Trả về phản hồi JSON với một URL tải xuống được ký (signed download URL) cho bản xuất dataset mới nhất.

Tham số truy vấn (Query Parameters):

Phản hồi (Response):

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

Tạo Phiên bản Dataset#

POST /api/datasets/{datasetId}/export

Tạo một bản chụp phiên bản được đánh số mới của tập dữ liệu. Thao tác này yêu cầu quyền Editor trở lên. Phiên bản này ghi lại số lượng hình ảnh, số lượng lớp, số lượng chú thích và phân phối tập chia hiện tại, sau đó tạo và lưu trữ một bản xuất NDJSON bất biến.

Request Body:

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

Tất cả các trường đều là 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 (Response):

{
    "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ó. Thao tác này yêu cầu quyền Editor trở lên.

Request Body:

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

Phản hồi (Response):

{
    "ok": true
}

Khôi phục phiên bản tập dữ liệu#

POST /api/datasets/{datasetId}/restore

Xây dựng lại hình ảnh, chú thích và các lớp của tập dữ liệu từ một phiên bản đã lưu mà không cần sao chép byte hình ảnh.

{
    "version": 2
}

Lấy Thống kê Lớp (Class Statistics)#

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

Trả về phân bổ lớp, bản đồ nhiệt vị trí (location heatmap) 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 (Response):

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

Quản lý Lớp (Classes)#

Hợp nhất các lớp (gán lại các annotation từ các lớp nguồn sang một lớp đích, sau đó xóa các lớp nguồn):

POST /api/datasets/{datasetId}/classes/merge

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

ID lớp là theo vị trí, do đó việc hợp nhất không phải là lũy đẳng (idempotent). Hãy tìm nạp lại tập dữ liệu trước khi thử lại.

Xóa các lớp:

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

Phân bổ lại Tập dữ liệu (Splits)#

POST /api/datasets/{datasetId}/splits/redistribute

Phân bổ lại ngẫu nhiên hình ảnh giữa các phân vùng train, validation và test. Tổng phần trăm phải bằng 100.

{
    "train": 80,
    "val": 20,
    "test": 0
}

Embeddings tập dữ liệu#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET trả về tóm tắt phân tích UMAP hiện tại và trạng thái công việc đang hoạt động; POST đưa công việc phân tích embeddings vào hàng đợi; DELETE hủy công việc đang hoạt động.

Phân cụm hình ảnh#

GET /api/datasets/{datasetId}/images/clustering

Trả về bố cục UMAP 2D và metadata cho mỗi hình ảnh trong chế độ xem phân tán (paged và rate-limited).

Lấy các Model đã huấn luyện trên Dataset#

GET /api/datasets/{datasetId}/models

Trả về các model đã được huấn luyện sử dụng dataset này.

Phản hồi (Response):

{
    "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 gán nhãn Dataset (Auto-Annotate)#

POST /api/datasets/{datasetId}/predict

Chạy inference YOLO trên các hình ảnh của dataset để 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 gán nhãn.

Body:

Nhập liệu Dataset (Ingest)#

POST /api/datasets/ingest

Tạo một tác vụ nạp (ingest) dữ liệu cho một tập dữ liệu hiện có. Tập dữ liệu đích luôn được truyền dưới dạng datasetId trong phần thân JSON, không phải trong đường dẫn URL.

Phần thân yêu cầu datasetId cộng với chính xác một trong hai sessionId (phiên bản tải lên của kho lưu trữ đã tải lên) hoặc sourceUrl (URL ZIP, TAR, TAR.GZ, TGZ, hoặc NDJSON từ xa). Thêm targetSplit (train, val, hoặc test) tùy chọn để ghi đè cấu trúc chia tách của kho lưu trữ. Để đính kèm siêu dữ liệu tùy chỉnh, hãy sử dụng imageMetadata, được khóa theo đường dẫn tương đối trong kho lưu trữ chính xác của từng hình ảnh hoặc giá trị NDJSON file.

Đối với các kho lưu trữ đã tải lên, phiên bản tải lên đã được liên kết với tập dữ liệu bằng assetId được truyền tới POST /api/upload/signed-url; quá trình nạp xác thực rằng assetId khớp với datasetId trong phần thân. Các mục classMapping tùy chọn ánh xạ từng tên lớp đến một chỉ mục lớp bắt đầu từ 0 hiện có, một tên lớp để tái sử dụng hoặc tạo mới, hoặc null để bỏ qua lớp đó. Đối với các tệp nhập từ xa sourceUrl, hãy tạo tập dữ liệu trước, sau đó truyền datasetId của nó để nạp.

Phần thân (tệp lưu trữ đã tải lên):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

Phần thân (một hoặc nhiều hình ảnh kèm theo siêu dữ liệu):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

Hình ảnh cục bộ sử dụng luồng tải lên kho lưu trữ hiện có, cho dù kho lưu trữ chứa một hay nhiều hình ảnh. Khóa phải khớp với đường dẫn đã chuẩn hóa bên trong kho lưu trữ, bao gồm cả các thư mục. Đối với các tệp nhập NDJSON, mỗi bản ghi hình ảnh có thể chứa đối tượng metadata của riêng nó. metadata cục bộ của bản ghi được ưu tiên hơn mục imageMetadata khớp.

Siêu dữ liệu ở định dạng JSON và hỗ trợ các giá trị lồng nhau. Đường dẫn kho lưu trữ bị giới hạn ở 1.024 ký tự, khóa siêu dữ liệu cấp cao nhất ở 128 ký tự và mỗi đối tượng siêu dữ liệu ở 500.000 ký tự được tuần tự hóa. Bản đồ imageMetadata hoàn chỉnh, hoặc siêu dữ liệu hiệu quả kết hợp qua một lần nhập NDJSON, cũng bị giới hạn ở 500.000 ký tự được tuần tự hóa. Các ràng buộc này được bao gồm trong lược đồ OpenAPI tương tác.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

Phần thân (tệp lưu trữ từ xa hoặc NDJSON):

{
    "datasetId": "dataset_abc123",
    "sourceUrl": "https://example.com/my-dataset.zip"
}

Phần thân (ingest sau, nhập nhãn):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

Phản hồi (Response):

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Hình ảnh Dataset#

Liệt kê hình ảnh#

GET /api/datasets/{datasetId}/images

Tham số truy vấn (Query Parameters):

Lấy hình ảnh đã chọn#

POST /api/datasets/{datasetId}/images

Trả về cùng hình dạng hình ảnh cho tối đa 1.000 ID hình ảnh được cung cấp. Nó chấp nhận các điều khiển truy vấn URL và nhãn tương tự như thao tác liệt kê.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

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ị trong 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 dataset:

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

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

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

Projects API#

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

Liệt kê Project#

GET /api/projects

Tham số truy vấn (Query Parameters):

Lấy Project#

GET /api/projects/{projectId}

Tạo Project#

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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Cập nhật Project#

PATCH /api/projects/{projectId}

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

{
    "metadata": { "department": "research", "program": "inspection" }
}

Gửi một đối tượng metadata trống ({}) để xóa nó. Metadata của project sử dụng cùng các giới hạn 128 ký tự cho khóa cấp cao nhất và 500.000 ký tự cho đối tượng được tuần tự hóa giống như metadata của dataset.

Lấy Metadata của Project#

GET /api/projects/{projectId}/metadata

Trả về đối tượng metadata tùy chỉnh và các cặp trường/giá trị do Ultralytics quản lý ở chế độ chỉ đọc. Cần phải xác thực và có quyền truy cập workspace của project.

Xóa Project#

DELETE /api/projects/{projectId}

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

Clone Dự án#

POST /api/projects/{projectId}/clone

Sao chép một dự án không gian làm việc công cộng, sở hữu hoặc có thể chỉnh sửa cùng với các mô hình của nó vào tài khoản hoặc không gian làm việc của bạn. Phần thân JSON tùy chọn chấp nhận name, slug, description, visibility, license, và ghi đè đích owner.

Biểu tượng Project#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

Tải lên một biểu tượng WebP có kích thước tối đa 5 MB dưới dạng trường form multipart image, hoặc xóa biểu tượng hiện tại.

API Models#

Quản lý các mô hình YOLO đã huấn luyện — xem các 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 mô hình.

Liệt kê Models#

GET /api/models

Tham số truy vấn (Query Parameters):

Liệt kê các Model đã hoàn tất#

GET /api/models/completed

Trả về tối đa 1.000 mô hình có trọng số khả dụng trên tất cả các dự án để huấn luyện và triển khai. Truyền owner cho một không gian làm việc.

Lấy Model#

GET /api/models/{modelId}

Tạo Model#

POST /api/models

JSON Body:

Cập nhật Model#

PATCH /api/models/{modelId}

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

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

Gửi một đối tượng metadata trống ({}) để xóa nó. Metadata tùy chỉnh của model tách biệt với thông tin model do quá trình huấn luyện sở hữu, thông tin chi tiết về môi trường và các đối số huấn luyện, đồng thời sử dụng các giới hạn về đối tượng được tuần tự hóa và khóa cấp cao nhất giống như metadata của dataset.

Lấy Metadata của Model#

GET /api/models/{modelId}/metadata

Trả về đối tượng metadata tùy chỉnh và các cặp trường/giá trị do Ultralytics quản lý ở chế độ chỉ đọc. Cần phải xác thực và có quyền truy cập workspace của model.

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 (Clone) Model#

POST /api/models/{modelId}/clone

Nhân bản một model công khai, do bạn sở hữu hoặc model không gian làm việc có thể chỉnh sửa sang một trong các dự án của bạn.

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

POST /api/models/{modelId}/predict

Các model công khai có thể được dự đoán mà không cần xác thực. Các model riêng tư và được chia sẻ yêu cầu một API key có quyền truy cập vào dự án gốc.

Multipart Form:

Cung cấp file hoặc source. Kích thước tải lên tối đa là 100 MB.

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 (Response):

Các phản hồi chứa shape, speed, results trên mỗi ảnh và dữ liệu bản đồ pixel dày đặc tùy chọn (bản đồ lớp ngữ nghĩa, hoặc bản đồ độ sâu trong đó depth = pixel × max / divisor — hệ số chia 255 cho bản đồ 8-bit mặc định, 65535 với bits=12|16), cộng với metadata chứa số lượng ảnh, thời gian thực thi hàm, tác vụ và các phiên bản dịch vụ. Các đường dẫn model nội bộ không bao giờ được trả về.

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

API Training#

Khởi chạy quá trình huấn luyện YOLO trên GPU đám mây (26 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 huấn luyện trên đám mây.

graph LR
    A[POST /training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET /models/id/training]:::proc
    C -->|cancel| E[DELETE /models/id/training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

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 khả dụng của GPU#

GET /api/training/gpu-availability

Trả về trạng thái kho GPU hiện tại (High, Medium, Low, hoặc null) được khóa theo ID loại GPU. Công khai, không cần xác thực; được bộ nhớ đệm trong 5 phút.

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, tiến trình, thời gian, thông tin GPU và các lỗi. Các dự án công khai có thể truy cập mà không cần xác thực; các dự án riêng tư và được chia sẻ yêu cầu một API key có quyền truy cập.

Hủy huấn luyện#

DELETE /api/models/{modelId}/training

Chấm dứt phiên bản tính toán đang chạy và đánh dấu công việc là đã hủy.

API Deployments#

Triển khai các mô hình tới các endpoint suy luận chuyên dụng kèm theo các kiểm tra trạng thái và tính năng giám sát. Các bản triển khai mới sử dụng tính năng thu nhỏ về 0 (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 endpoint.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|stop| D[Stopped]:::extern
    D -->|start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Liệt kê các bản triển khai#

GET /api/deployments

Tham số truy vấn (Query Parameters):

Tạo bản 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 endpoint inference chuyên dụng trong khu vực được chỉ định. Endpoint có thể truy cập toàn cầu thông qua một URL duy nhất.

Lấy bản triển khai#

GET /api/deployments/{deploymentId}

Xóa bản triển khai#

DELETE /api/deployments/{deploymentId}

Bắt đầu bản triển khai#

POST /api/deployments/{deploymentId}/start

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

Dừng bản triển khai#

POST /api/deployments/{deploymentId}/stop

Ngừng phục vụ các yêu cầu bằng cách đặt số lượng instance tối thiểu và tối đa của dịch vụ về không.

Kiểm tra tình trạng#

GET /api/deployments/{deploymentId}/health

Trả về trạng thái tình trạng của endpoint triển khai.

Chạy Inference trên bản triển khai#

POST /api/deployments/{deploymentId}/predict

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

Multipart Form:

Cung cấp file hoặc source. Phản hồi sử dụng cùng một hợp đồng hình ảnh và siêu dữ liệu như tính năng dự đoán mô hình và không bao giờ trả về đường dẫn mô hình nội bộ.

Lấy số liệu#

GET /api/deployments/{deploymentId}/metrics

Trả về số lượng yêu cầu, độ trễ và số liệu tỷ lệ lỗi cùng với dữ liệu biểu đồ sparkline.

Tham số truy vấn (Query Parameters):

Lấy nhật ký (logs)#

GET /api/deployments/{deploymentId}/logs

Tham số truy vấn (Query Parameters):

API Xuất#

Chuyển đổi các mô hình sang các định dạng được tối ưu hóa như ONNX, TensorRT, CoreML, và LiteRT để triển khai trên biên. Xem Tài liệu triển khai.

Danh sách Xuất#

GET /api/exports

Tham số truy vấn (Query Parameters):

Tạo 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ợ:

Sử dụng tham số format từ bảng xuất chung bên dưới. PyTorch là định dạng nguồn và không phải là mục tiêu xuất API.

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

GET /api/exports/{exportId}

Hủy xuất#

DELETE /api/exports/{exportId}

Theo dõi tải xuống bản xuất#

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

API Hoạt động#

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

Liệt kê hoạt động#

GET /api/activity

Tham số truy vấn (Query Parameters):

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

POST /api/activity/mark-seen

Body:

{
    "all": true
}

Hoặc chuyển các ID cụ thể:

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

Truyền tham số truy vấn tùy chọn owner để đánh dấu các sự kiện trong một không gian làm việc.

Lưu trữ sự kiện#

POST /api/activity/archive

Body:

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

Hoặc chuyển các ID cụ thể:

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

Truyền tham số truy vấn tùy chọn owner để lưu trữ hoặc khôi phục các sự kiện trong không gian làm việc.

API Thùng rác#

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

Liệt kê thùng rác#

GET /api/trash

Tham số truy vấn (Query Parameters):

Khôi phục mục#

POST /api/trash

Body:

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

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

DELETE /api/trash

Body:

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

Làm trống 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, mức sử dụng gói cước và lịch sử giao dịch của bạn. Xem Tài liệu thanh toán.

Các endpoint số dư và giao dịch chấp nhận tham số truy vấn tùy chọn owner với tên người dùng của chủ sở hữu không gian làm việc.

Lấy số dư#

GET /api/billing/balance

Phản hồi (Response):

{
    "creditsCents": 2500,
    "plan": "free"
}

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à số liệu sử dụng.

Lấy giao dịch#

GET /api/billing/transactions

Trả về lịch sử giao dịch (gần nhất trước tiên).

Các giao dịch bao gồm các trường sổ cái hướng tới khách hàng như số tiền, số dư kết quả, ngày tháng, bối cảnh model tùy chọn và URL biên lai. Ghi chú nội bộ, ID thanh toán/hoàn tiền Stripe và khóa lũy đẳng không được trả về.

API Lưu trữ#

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

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

GET /api/storage

Tham số truy vấn (Query Parameters):

Phản hồi (Response):

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

Tích hợp lưu trữ đám mây#

Kết nối và duyệt các tích hợp lưu trữ GCS, S3 hoặc Azure Blob chỉ đọc:

GET /api/integrations/buckets
POST /api/integrations/buckets
POST /api/integrations/buckets/discover
GET /api/integrations/buckets/{id}/objects

Cả bốn thao tác đều chấp nhận tham số truy vấn tùy chọn owner cho một không gian làm việc. Việc duyệt đối tượng cũng chấp nhận target bắt buộc cộng với các tham số truy vấn prefix tùy chọn và cursor của nhà cung cấp. Phần thân yêu cầu kết nối và khám phá sử dụng các lược đồ thông tin xác thực của nhà cung cấp trong tài liệu tham khảo OpenAPI tương tác; thông tin xác thực không bao giờ được trả về.

API Tải lên#

Tải tệp trực tiếp lên bộ nhớ đám mây bằng các URL có chữ ký để truyền dữ liệu nhanh chóng và đáng tin cậy. Việc hoàn thành việc tải lên mô hình sẽ đính kèm trọng số của nó. Việc hoàn thành việc tải lên kho lưu trữ tập dữ liệu sẽ ghi lại phiên làm việc; hãy truyền sessionId đó đến POST /api/datasets/ingest để bắt đầu xử lý. Xem Tài liệu dữ liệu.

Lấy Signed URL Tải lên#

POST /api/upload/signed-url

Yêu cầu một signed URL để tải tệp trực tiếp lên bộ nhớ đám mây. Signed URL sẽ bỏ qua máy chủ API để thực hiện truyền tệp dung lượng lớn.

Body:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Phản hồi (Response):

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.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 việc tải tệp lên đã hoàn tất. Đối với các mô hình, thao tác này đính kèm các trọng số đã tải lên. Đối với các kho lưu trữ tập dữ liệu, thao tác này xác minh và ghi lại phiên tải lên; hãy gọi POST /api/datasets/ingest sau đó để bắt đầu xử lý tập dữ liệu.

Body:

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

API Tích hợp#

Nhập các tập dữ liệu từ các dịch vụ của bên thứ ba. Xem Tài liệu tích hợp.

Xem trước Nhập từ Roboflow#

POST /api/integrations/roboflow/preview

Giải mã API key Roboflow sang một gói nhập hàng loạt: thông tin workspace, những dự án nào sẽ được nhập mới, số lượng phiên bản đã nhập (bị bỏ qua) và các loại dự án không được hỗ trợ. API key Roboflow được truyền trong phần thân yêu cầu và không được lưu lại.

Nhập từ Roboflow#

POST /api/integrations/roboflow/import

Xếp hàng các công việc nạp dữ liệu để nhập các dự án Roboflow đã chọn vào workspace của bạn. Yêu cầu dung lượng lưu trữ, và mỗi tập dữ liệu phải phù hợp với giới hạn kích thước mỗi lần nhập trong gói của bạn.

API API Keys#

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

Liệt kê các API Keys#

GET /api/api-keys

Các client được xác thực bằng API key nhận được siêu dữ liệu của khóa, không bao giờ nhận được giá trị khóa hiện có đã giải mã. Một khóa mới được tạo chỉ được trả về một lần bởi POST /api/api-keys.

Truyền tham số truy vấn tùy chọn owner để quản lý các khóa cho một không gian làm việc nơi bạn có quyền chỉnh sửa.

Tạo API Key#

POST /api/api-keys

Body:

{
    "name": "training-server"
}

Xóa API Key#

DELETE /api/api-keys

Tham số truy vấn (Query Parameters):

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ý các vai trò để cộng tác. Xem Tài liệu 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ê các 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 nhượng Quyền sở hữu#

POST /api/members/transfer-ownership

API Khám phá (Explore)#

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

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

GET /api/explore/search

Tham số truy vấn (Query Parameters):

Dữ liệu Thanh bên#

GET /api/explore/sidebar

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

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

Quản lý hồ sơ, các API key, mức sử dụng lưu trữ và không gian làm việc nhóm của bạn. Xem Tài liệu cài đặt.

Tóm tắt tài khoản#

GET /api/account/summary

Trả về gói, số dư tín dụng, số lượng tài nguyên và các không gian làm việc nhóm của tài khoản đã xác thực.

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

GET /api/users

Tham số truy vấn (Query Parameters):

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 tính sẵn sàng của Tên người dùng#

GET /api/username/check

Tham số truy vấn (Query Parameters):

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 mạng xã hội, v.v.).

Biểu tượng không gian làm việc#

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

Tải lên một biểu tượng hồ sơ/không gian làm việc WebP kích thước tối đa 5 MB dưới dạng trường form multipart image, hoặc xóa nó. Truyền owner tùy chọn cho một không gian làm việc nhóm.

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ý việc xác thực, tải lên và phát trực tuyến các chỉ số theo thời gian thực.

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

pip install "ultralytics>=8.4.104"

Xác minh cài đặt:

yolo check

Xác thực#

yolo login YOUR_API_KEY

Sử dụng tập dữ liệu (dataset) của Platform#

Tham chiếu các tập dữ liệu với các 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 dữ liệu lên Platform#

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

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ộ:

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

Ví dụ về API#

Tải model từ Platform:

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

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

Chạy suy luận (inference):

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, quantize=16)

# Export to TensorRT
model.export(format="engine", imgsz=640, quantize=16)

# Export to CoreML
model.export(format="coreml", imgsz=640)  # use imgsz=224 for classification

Xác thực (Validation):

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

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

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

Làm cách nào để phân trang (paginate) các kết quả lớn?#

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

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

Các endpoint Hoạt động và Thùng rác cũng hỗ trợ tham số page để phân trang dựa trên 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ác thao tác REST công khai được tài liệu hóa ở trên có sẵn mà không cần Python SDK. SDK là một trình bao bọc tiện lợi bổ sung các tính năng như truyền trực tuyến metric thời gian thực và tự động tải mô hình lên. Bạn có thể khám phá hợp đồng có thể đọc bằng máy một cách tương tác tại platform.ultralytics.com/api/docs; các luồng tài khoản chỉ dành cho phiên trình duyệt vẫn nằm trong Platform UI.

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

Sử dụng gói Ultralytics Python hoặc thực hiện các yêu cầu HTTP trực tiếp từ bất kỳ ngôn ngữ nào.

Làm cách 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ờ khoảng thời gian phù hợp:

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 RuntimeError("Rate limit exceeded")

Làm cách nào để tìm ID của model hoặc tập dữ liệu?#

ID tài nguyên được trả về bởi các phản hồi API tạo, liệt kê và lấy. Các URL trang Platform sử dụng slug dễ đọc đối với con người, không phải ID cơ sở dữ liệu:

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

Sử dụng các endpoint danh sách để tìm _id tương ứng cho một model, dataset, project, deployment hoặc tài nguyên khác.