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

Ultralytics Platform cung cấp REST API để truy cập theo chương trình vào các dataset, image, project, model, hoạt động training, export và deployment.

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

Tổng quan về API#

API được tổ chức xoay quanh các resource cốt lõi của Platform:

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

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

Xác thực#

Hầu hết endpoint yêu cầu API key. Các endpoint cung cấp nội dung công khai — đọc dataset, project hoặc model công khai, liệt kê image của dataset công khai, chạy inference trên model công khai hoặc tìm kiếm trong Explore — cũng chấp nhận request ẩn danh và chỉ trả về nhiều dữ liệu hơn khi có key.

Lấy API Key#

1. Truy cập Settings > API Keys
2. Click Create Key
3. Sao chép key đã tạo

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

Header ủy quyền#

Gửi API key của bạn dưới dạng bearer token:

Authorization: Bearer YOUR_API_KEY

Ví dụ#

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

Base URL#

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

https://platform.ultralytics.com/api

Đường dẫn resource#

Resource được định danh bằng cùng tên dễ đọc với tên xuất hiện trong URL của Platform, không phải bằng database ID:

• {owner} là username cá nhân hoặc handle workspace của team: từ 4-32 ký tự, gồm chữ và số viết thường với dấu gạch nối đơn giữa các phân đoạn.
• {dataset}, {project}, {model} và {deployment} tuân theo cùng pattern chữ thường phân tách bằng dấu gạch nối, tối đa 128 ký tự.
• {imageId} và {exportId} là các ID thập lục phân dài 24 ký tự do API trả về.
• Đổi tên resource thông qua PATCH sẽ đồng thời thay đổi name hiển thị và tên URL; response trả về tên URL hiện tại để bạn có thể tiếp tục sử dụng tên đó.

Giới hạn tốc độ#

API áp dụng giới hạn theo cửa sổ trượt cho từng API key. Mỗi route thuộc một category và mỗi category có bộ đếm độc lập, vì vậy 20 request predict không tiêu hao hạn mức mặc định của bạn.

Các route Platform chỉ dành cho trình duyệt, chẳng hạn như thanh toán billing và quản lý team, có giới hạn riêng không áp dụng cho traffic sử dụng API key.

Khi bị throttling, API trả về 429 cùng với cả header và JSON body:

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

{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

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

Endpoint chuyên dụng không chịu giới hạn tốc độ API key của Platform khi bạn gọi trực tiếp serviceUrl riêng của deployment (ví dụ: https://predict-abc123.run.app/predict). Khi đó, throughput phụ thuộc vào cấu hình service đã deploy.

Định dạng Response#

Response thành công#

Response là các object JSON với những field dành riêng cho từng resource. Không có envelope tổng quát: endpoint list trả về một collection có tên cùng với các số đếm, còn mutation trả về các identifier đã thay đổi.

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

Các response chứa dữ liệu cũng bao gồm region (us, eu hoặc ap), tức region storage của workspace đó.

Response lỗi#

Mọi response lỗi đều là một object JSON với message error:

{
    "error": "Dataset not found"
}

Phân trang#

Kiểu phân trang phụ thuộc vào collection:

Datasets API#

Tạo, duyệt và quản lý các dataset ảnh đã gán nhãn để training model YOLO. Xem tài liệu Datasets.

Liệt kê Datasets#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Trả về các dataset công khai của chủ sở hữu, cùng với các dataset riêng tư khi key của bạn có quyền xem workspace đó.

Tham số Query:

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

Response:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Lấy Dataset#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

Trả về toàn bộ object dataset dưới key dataset, bao gồm classNames, splits, versions, source và object do người dùng định nghĩa metadata.

Tạo Dataset#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

Body:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

Phản hồi trả về chuỗi định danh dataset thực sự được tạo, vì vậy hãy đọc lại trước khi tải lên trừ khi bạn thiết lập requireExactSlug.

Response (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

Cập nhật Dataset#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

Body (partial update):

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

Các field được chấp nhận: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter và starred. Gửi một object metadata rỗng ({}) để xóa metadata tùy chỉnh. Key metadata bị giới hạn ở 128 ký tự và object được serialize ở 500.000 ký tự.

Response:

{
    "success": true,
    "dataset": "warehouse-safety"
}

Việc đổi tên sẽ thay đổi tên URL, vì vậy hãy sử dụng giá trị dataset được trả về cho các request tiếp theo.

Xóa Dataset#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

Chuyển dataset vào thùng rác, nơi có thể khôi phục trong 30 ngày.

Clone Dataset#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

Sao chép một dataset có quyền truy cập, cùng với ảnh và label của dataset đó, vào workspace cá nhân hoặc team workspace của bạn.

Body tùy chọn (tất cả field đều không bắt buộc):

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

Response (201): id, owner, dataset, name, imageCount, classCount và region. Các dataset được hỗ trợ bởi nguồn storage đã kết nối trả về 409 vì các file của chúng không được sao chép.

Tải xuống Export của Dataset#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

Trả về URL tải xuống NDJSON có chữ ký. Bỏ qua v để export trạng thái hiện tại của dataset, sử dụng lại export đã cache khi không có thay đổi nào kể từ lúc export được tạo.

Tham số Query:

Response:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

Yêu cầu một phiên bản cụ thể sẽ trả về downloadUrl và version thay vì cached.

Tạo Version của Dataset#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

Tạo snapshot bất biến được đánh số của dataset và lưu export NDJSON của dataset. Yêu cầu quyền editor.

Body (tùy chọn):

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

Response:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

reused là true khi dataset không thay đổi kể từ version trước đó và snapshot đó được trả về thay thế.

Cập nhật Mô tả Version#