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

Ultralytics Platform cung cấp REST API để truy cập bằng chương trình vào dataset, hình ảnh, project, model, quá trình 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 tài nguyên cốt lõi của Platform:

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ê hình ảnh của dataset công khai, chạy suy luận trên model công khai hoặc tìm kiếm trong Khám phá — cũng chấp nhận yêu cầu ẩn danh và chỉ trả về nhiều thông tin hơn khi có API key.

Lấy API key#

1. Truy cập Settings > API Keys
2. Nhấp vào Add Key, giữ nguyên Ultralytics làm nhà cung cấp, nhập tên rồi nhấp vào Create Key
3. Sao chép key vừa tạo

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

Header xác thực#

Gửi API key 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

URL cơ sở#

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

https://platform.ultralytics.com/api

Đường dẫn tài nguyên#

Hầu hết tài nguyên được truy cập bằng tên dễ đọc giống như tên xuất hiện trong URL của Platform, không phải bằng ID cơ sở dữ liệu:

• {owner} là tên người dùng cá nhân hoặc handle của workspace nhóm: gồm 4-32 ký tự, chữ và số viết thường, các đoạn được phân tách bằng dấu gạch nối đơn.
• {dataset}, {project}, {model} và {deployment} tuân theo cùng định dạng chữ thường phân tách bằng dấu gạch nối, tối đa 128 ký tự.
• {imageId}, {exportId} và {agentId} là ID thập lục phân gồm 24 ký tự do API trả về.
• Đổi tên tài nguyên bằng PATCH sẽ đồng thời thay đổi name hiển thị và tên trong URL; phản hồi trả về tên URL hiện tại để bạn có thể tiếp tục truy cập tài nguyê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 danh mục và mỗi danh mục có bộ đếm riêng, vì vậy 20 yêu cầu dự đoán sẽ không làm giảm hạn mức mặc định của bạn.

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

Khi bị giới hạn tốc độ, API trả về 429 cùng với cả header và phần thân JSON:

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

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

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 độ API key của Platform khi bạn gọi trực tiếp serviceUrl của deployment (ví dụ: https://predict-abc123.run.app/predict). Khi đó, thông lượng phụ thuộc vào cấu hình dịch vụ được triển khai.

Định dạng response#

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

Phản hồi là các đối tượng JSON có trường dành riêng cho từng tài nguyên. Không có envelope chung: endpoint danh sách trả về một collection có tên, thường kèm theo số lượng, còn các thao tác thay đổi trả về những mã định danh đã thay đổi.

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

Danh sách tài nguyên, phản hồi tạo và sao chép, cùng một số phản hồi đọc như deployments, storage và trash cũng bao gồm region (us, eu hoặc ap), tức vùng lưu trữ của workspace đó.

Phản hồi lỗi#

Mọi phản hồi lỗi đều là đối tượng JSON có thông báo error:

{
    "error": "Dataset not found"
}

Phân trang#

Kiểu phân trang tùy thuộc vào collection:

API Datasets#

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ê dataset#

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 các dataset riêng tư nếu API key của bạn có quyền xem workspace đó.

Tham số truy vấn:

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

Phản hồi:

{
    "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ộ đối tượng dataset trong khóa dataset, bao gồm classNames, splits, versions, source và đối tượng metadata do người dùng xác định. Trong khi quá trình import 10.000 ảnh trở lên đang diễn ra, editor cũng nhận được processingProgress với stage, percent và, nếu đã biết, processed, total và objects (các đối tượng cloud đã quét).

Tạo dataset#

POST /api/datasets

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

Phần thân:

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

Một slug dataset đã tồn tại trong workspace, kể cả slug trong Trash, sẽ trả về 409.

Phản hồi (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)

Phần thân (cập nhật một phần):

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

Các trường được chấp nhận: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter, starred, blurFaces, kptSkeletonId (gán template skeleton pose cho dataset pose) và initializeClassNames (phản hồi cập nhật trả về 409, trừ khi dataset chưa có class hoặc annotation). Gửi một đối tượng metadata rỗng ({}) để xóa metadata tùy chỉnh. Khóa metadata có giới hạn 128 ký tự và đối tượng sau khi tuần tự hóa có giới hạn 500.000 ký tự.

Phản hồi:

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

Đổi tên sẽ thay đổi tên URL, vì vậy hãy dùng giá trị dataset được trả về cho các yêu cầu tiếp theo.

Xóa dataset#

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

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

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

Sao chép dataset#

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

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

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

Phần thân không bắt buộc (mọi trường đề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"
}

Phản hồi (201): id, owner, dataset, name, imageCount, classCount và region. Dataset được liên kết với nguồn storage sẽ trả về 409 vì các tệp của dataset không được sao chép.

Tải bản export dataset xuống#

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 và tái sử dụng bản export đã lưu trong cache nếu không có thay đổi nào kể từ lần tạo trước.

Tham số truy vấn:

Phản hồi:

{
    "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 phiên bản dataset#

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

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

Tạo một phiên bản được đánh số và bất biến của dataset. Yêu cầu quyền editor. Đặt download thành false để lưu phiên bản mà không chuẩn bị bản tải xuống NDJSON; khi đó, downloadUrl sẽ bị lược bỏ. SDK chấp nhận download từ ultralytics-platform>=0.1.73.

Phần thân (không bắt buộc):

{
    "description": "Added 500 training images",
    "download": true
}

Phản hồi:

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

reused là true khi dataset khớp với một phiên bản hiện có, chẳng hạn ngay sau khi khôi phục; thay vào đó, phiên bản đó sẽ được trả về và mô tả sẽ được cập nhật nếu bạn gửi mô tả.

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

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

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

Phần thân:

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

Phản hồi: {"ok": true}

Khôi phục phiên bản dataset#

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

Python SDK: client.datasets.restore(owner, dataset, version=...)

Tạo lại ảnh, annotation và class từ phiên bản đã lưu mà không sao chép dữ liệu ảnh.

Phần thân:

{
    "version": 2
}

Phản hồi: {"version": 2, "imageCount": 1000}

So sánh các phiên bản dataset#

GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}

Python SDK: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)

Phản hồi (rút gọn):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summary chỉ xuất hiện ở trang đầu tiên và chứa tổng số chính xác cùng với header, liệt kê các class được thêm, xóa hoặc đổi tên cùng những trường dataset khác có sự khác biệt. change của mỗi mục là added, removed, modified (có fields đã thay đổi) hoặc moved (split đã thay đổi), còn labelsRemoved bao gồm nhãn của các ảnh đã xóa. Nếu có nextCursor, hãy truyền giá trị đó làm cursor cho trang tiếp theo. Với hash, phản hồi là versions: ảnh như được lưu trong từng phiên bản, kèm nhãn và imageUrl có chữ ký. Có thể dùng cả hai thứ tự; nếu hoán đổi base và head, ảnh đã xóa sẽ được báo cáo là ảnh được thêm. So sánh sử dụng giới hạn tốc độ mặc định; các yêu cầu không có hash cũng bị giới hạn ở mức 10 lần mỗi phút cho mỗi người dùng và dataset, bất kể API key nào gửi yêu cầu.

Lấy thống kê dataset#

GET /api/datasets/{owner}/{dataset}/class-stats

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

Trả về số lượng chú thích theo từng lớp, biểu đồ histogram của ảnh và chú thích, cùng heatmap. Dataset lớn sẽ được lấy mẫu; trong trường hợp đó, sampleSize báo số ảnh đã được dùng.

Phản hồi (rút gọn):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

Quản lý lớp#

Gộp lớp (gán lại chú thích cho lớp đích, sau đó xóa các lớp nguồn):

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

Xóa lớp (chú thích của các lớp đó cũng bị xóa và ID của những lớp còn lại sẽ giảm):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

Cả hai thao tác đều trả về success, classNames và classColors đã cập nhật, cùng bản tóm tắt các thay đổi (mergedClassIds và targetClassId, hoặc deletedClassIds và deletedAnnotations).

Phân phối lại các tập dữ liệu#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

Gán lại ngẫu nhiên ảnh giữa các tập dữ liệu. Tổng ba tỷ lệ phần trăm phải bằng 100.

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

Phản hồi: success, số lượng splits sau khi phân phối, và modified (số ảnh đã di chuyển).

Embedding của dataset#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)

GET trả về bản tóm tắt phân tích (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST đưa tác vụ phân tích embedding vào hàng đợi và trả về 202 cùng jobId. DELETE hủy tác vụ đang hoạt động và trả về ID tác vụ đã hủy hoặc null.

Phân cụm ảnh#

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

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

Trả về bố cục 2D UMAP từ một phân tích đã hoàn tất, có phân trang bằng offset và limit (mặc định và tối đa là 50.000). Mỗi mục có id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled và missing. cluster là đảo trực quan chứa điểm dữ liệu, được xếp hạng theo kích thước (0 = lớn nhất, -1 = phân tán), hoặc null đối với các bố cục được phân tích trước khi tính năng phân cụm được bổ sung.

Liệt kê model được huấn luyện trên dataset#

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

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

Phản hồi:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

Liệt kê ảnh trong dataset#

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

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

Tham số truy vấn:

Phản hồi:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

Lấy ảnh đã chọn#

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

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

Trả về cấu trúc dữ liệu ảnh tương tự cho tối đa 1.000 ID ảnh được cung cấp, đồng thời chấp nhận cùng các tham số truy vấn bộ lọc và URL như thao tác liệt kê.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Sao chép hoặc di chuyển ảnh#

POST /api/datasets/{owner}/{dataset}/images/adopt

Python SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

Sao chép tối đa 1.000 ảnh từ các dataset khác vào dataset này, tương tự tính năng sao chép và dán của ứng dụng, đồng thời trả về số lượng adopted.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

Thiết lập release hoặc classMapping sẽ giữ lại nhãn và các tập dữ liệu từ dataset mà bạn có thể chỉnh sửa: release: false sao chép hình ảnh, còn release: true chuyển hình ảnh khỏi dataset nguồn. Nếu bỏ qua cả hai trường, hình ảnh train không có nhãn sẽ được nhập; thao tác sao chép từ nguồn chỉ đọc cũng có kết quả tương tự. Di chuyển từ nguồn chỉ đọc sẽ trả về 403. Các hình ảnh đã tồn tại sẽ bị bỏ qua; khi giữ lại nhãn và các tập dữ liệu, hình ảnh trùng lặp được kiểm tra trong tập dữ liệu đích. Các class được đối chiếu theo tên, không phân biệt chữ hoa chữ thường với tên dài hơn hai ký tự; 422 trả về các class nguồn không có kết quả khớp trong unmatchedClasses, còn classMapping ánh xạ từng class vào một chỉ số class, tên class mới hoặc null để loại bỏ nhãn của class đó. 409 nghĩa là đích là dataset được kết nối hoặc nguồn hay đích đang bận. Khi giữ lại nhãn và các tập dữ liệu, các tác vụ, kênh hình ảnh, cài đặt pose hoặc thang đo depth không tương thích cũng trả về 409, kể cả với hình ảnh không có nhãn.

Nhập dữ liệu dataset#

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

Python SDK: client.datasets.ingest(owner, dataset, body=...)

Xử lý một lượt tải lên đã hoàn tất, một archive từ xa hoặc một nguồn lưu trữ được kết nối để đưa dữ liệu vào dataset hiện có. Chỉ cung cấp chính xác một nguồn:

Phiên tải lên được liên kết với một dataset thông qua assetId được truyền cho POST /api/upload/signed-url; thao tác nhập sẽ từ chối phiên thuộc dataset khác.

Body (archive đã tải lên):

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

Body (archive từ xa hoặc NDJSON):

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

Body (nhập nhãn trong lần nhập sau):

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

Body (đính kèm metadata cho từng ảnh):

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

Khóa metadata phải khớp với đường dẫn đã chuẩn hóa bên trong archive, bao gồm cả thư mục. Với các lượt nhập NDJSON, mỗi bản ghi có thể chứa đối tượng metadata riêng; đối tượng này được ưu tiên hơn mục imageMetadata tương ứng. Đường dẫn trong archive giới hạn ở 1.024 ký tự, khóa metadata cấp cao nhất giới hạn ở 128 ký tự và mỗi đối tượng metadata — cũng như toàn bộ map imageMetadata — giới hạn ở 500.000 ký tự sau khi tuần tự hóa.

Phản hồi (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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()

headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, 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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

API ảnh#

Kiểm tra, gắn nhãn, di chuyển và xóa ảnh trong dataset bằng ID ảnh gồm 24 ký tự. Xem tài liệu về chú thích.

Lấy ảnh#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Trả về đối tượng metadata (tùy chỉnh, do người dùng định nghĩa), properties (tên tệp, hash, kích thước, tập dữ liệu, số lượng, dấu thời gian), labels và classNames của dataset.

Cập nhật ảnh#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

Thay thế một trong hai: chú thích hoặc metadata tùy chỉnh — chỉ gửi một trong hai cấu trúc, không gửi cả hai.

Body (chú thích):

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

Body (metadata):

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

Xóa ảnh#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Xóa vĩnh viễn một ảnh cùng các chú thích của ảnh đó.

Tự động gắn nhãn ảnh#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

Chạy model trên ảnh và trả về các chú thích dự đoán. Các chú thích này không được lưu — hãy ghi kết quả trở lại bằng PATCH /api/images/{imageId} khi bạn đã hài lòng.

Phản hồi: success, predictions (các đối tượng chú thích), confidences (điểm số căn chỉnh theo chỉ số, để trống với model có prompt lớp), modelUsed, inferenceTime; với model có prompt lớp, partial (true khi đầu ra bị cắt cụt của model tạo sinh chỉ trả về các bounding box hoàn chỉnh); và với model của nhà cung cấp có tính phí, có thể có cost (chi phí ước tính của nhà cung cấp tính bằng USD, được tính vào khóa nhà cung cấp của bạn; trường này bị lược bỏ nếu không có ước tính). Model YOLO có các lớp không khớp với dataset sẽ trả về 422; lỗi tương tự xảy ra với model có prompt lớp khi dùng trên dataset không phải detection hoặc dataset có số lớp ngoài khoảng 1–200, cũng như với model của nhà cung cấp có tính phí khi dataset workspace chưa lưu khóa nhà cung cấp trong Settings > API Keys (code: missing_provider_api_key). Lỗi từ nhà cung cấp kèm theo thông báo của nhà cung cấp: 422 khi nhà cung cấp trả lời 400, 401, 403 hoặc 404 (khóa, model hoặc yêu cầu bị từ chối), 429 khi vượt giới hạn tốc độ và 503 với mọi lỗi khác từ nhà cung cấp. Dataset độ sâu trả về 400; dataset dùng lưu trữ được kết nối hoặc có hơn 3 kênh ảnh trả về 409.

Tìm ảnh tương tự#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

Trả về tối đa 24 images tương tự về mặt hình ảnh từ các dataset công khai và dataset của bạn cũng như của nhóm, mỗi ảnh có score (0-1), một URL có chữ ký thumbnailUrl và dataset nguồn (owner, dataset, license). Ảnh đã có trong dataset nguồn và bản sao của ảnh truy vấn sẽ bị loại trừ. Cần có API key với quyền xem ảnh; ảnh chưa được embedding sẽ được embedding trước, còn 503 có nghĩa là bước chuẩn bị thất bại và cần thử lại.

Tự động gắn nhãn dataset#

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)

Lưu một phiên bản dataset, sau đó đưa vào hàng đợi một lượt chạy để gắn nhãn các ảnh chưa có nhãn trong dataset bằng model và trả về 202. Body nhận các trường modelId, confidence, iou và classMapping giống endpoint xử lý một ảnh, cùng với includeAnnotated (mặc định false) để gắn nhãn cả những ảnh đã có nhãn. Model có prompt lớp sẽ phát hiện các lớp của dataset mà không có điểm confidence; model của nhà cung cấp có tính phí cần có khóa nhà cung cấp được lưu trong dataset workspace tại Settings > API Keys (422, code: missing_provider_api_key, trước khi lượt chạy được chấp nhận). Nhãn hiện có không bao giờ bị thay đổi và lượt chạy được tính phí theo số ảnh thực tế đã xử lý. 402 có nghĩa là số dư không đủ để thanh toán khoản ước tính; 409 có nghĩa là dataset chưa sẵn sàng, không còn ảnh để gắn nhãn hoặc đã có lượt chạy đang diễn ra; 422 có nghĩa là dataset không có lớp, hoặc model có prompt lớp được dùng với dataset không phải detection hay dataset có số lớp ngoài khoảng 1–200: hãy tạo lớp bằng endpoint lớp trước khi gọi endpoint này; ứng dụng thực hiện bước đó trong bước Map classes trước khi bắt đầu lượt chạy.

GET trên cùng đường dẫn (client.datasets.batch(owner, dataset)) trả về lượt chạy đang thực hiện cùng tiến độ, hoặc lượt chạy gần nhất đã hoàn tất cho đến khi bị loại bỏ; results của lượt chạy bao gồm partialImages khi lượt chạy của model tạo sinh chỉ giữ lại các bounding box hoàn chỉnh từ đầu ra bị cắt cụt. DELETE (client.datasets.delete_batch(owner, dataset)) hủy lượt chạy đang thực hiện hoặc chốt thanh toán và loại bỏ bản tóm tắt đã hoàn tất.

Endpoint tương tự làm mờ khuôn mặt bằng "operation": "blur", confidence (mặc định 0.25) và boxScale (0.5–1.5, mặc định 1); imageId giới hạn lượt chạy ở một ảnh. Endpoint không tạo phiên bản và không bao giờ thay đổi nhãn. Gửi "preview": true để xử lý tối đa sáu ảnh mà không thay đổi chúng, sau đó gửi jobId được trả về làm previewJobId cùng các thiết lập tương tự để áp dụng; không thể sử dụng lại bản xem trước đã áp dụng và endpoint sẽ trả về 409. Khi bản xem trước đang chờ, hãy truyền ID của bản xem trước làm previewJobId cho DELETE để loại bỏ bản xem trước.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

Di chuyển hàng loạt ảnh#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

Di chuyển tối đa 1.000 ảnh từ một dataset sang tập dữ liệu khác.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

Xung đột tên tệp hoặc nội dung sẽ trả về 409 cho đến khi bạn chọn conflictPolicy áp dụng cho toàn bộ nhóm: skip, keep_both hoặc replace. Phản hồi báo cáo modifiedCount, skippedCount và targetSplit.

Xóa hàng loạt ảnh#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

Xóa tối đa 1.000 ảnh trong một dataset và trả về deletedCount cùng deletedImageIds.

Lấy URL ảnh có chữ ký#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

Trả về URL tạm thời có chữ ký cho tối đa 100 ID ảnh thuộc cùng một dataset.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

Phản hồi: urls, thumbnails và depths (bản xem trước mục tiêu độ sâu cho các ảnh độ sâu được ghép cặp), tất cả được khóa theo ID ảnh.

API dự án#

Sắp xếp các model thành dự án. Mỗi model thuộc về một dự án. Xem tài liệu về dự án.

Liệt kê dự án#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

Tham số truy vấn:

Lấy dự án#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

Trả về đối tượng project, một mảng models gồm bản tóm tắt cho từng model (trạng thái, metric, epoch, weights, tham số huấn luyện), và isOwner. Truyền search (tối đa 200 ký tự) để lọc models theo tên model hoặc metadata.

Tạo project#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Phản hồi (201): id, owner, project, region.

Một slug project đã tồn tại trong workspace, kể cả slug trong Trash, sẽ trả về 409.

Cập nhật dự án#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

Các trường được chấp nhận: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences và starred.

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

Gửi một object metadata rỗng ({}) để xóa object đó. Metadata dự án sử dụng cùng giới hạn 128 ký tự cho khóa và 500.000 ký tự cho object được tuần tự hóa như metadata tập dữ liệu.

Xóa dự án#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

Chuyển dự án và các model của dự án vào thùng rác, trả về cascadedModels và xóa vĩnh viễn các deployment của dự án. Khôi phục dự án không khôi phục các deployment. 502 có nghĩa là quá trình dọn dẹp deployment chưa hoàn tất; các model vẫn nằm trong Thùng rác cho đến khi quá trình này thành công.

Sao chép dự án#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

Sao chép một dự án có thể truy cập và các model đã hoàn tất của dự án đó. Body tùy chọn chấp nhận project, name, description, visibility, license và owner làm đích đến.

API Models#

Quản lý các model YOLO đã huấn luyện — xem metrics, tải weights xuống, chạy inference và theo dõi quá trình huấn luyện. Xem tài liệu Models.

Liệt kê Models trong một dự án#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

Tham số truy vấn:

Lấy Model#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

Tham số truy vấn:

Phản hồi mặc định chứa object model — trạng thái, tác vụ, metrics, trainArgs, trainResults, classNames, computeCost, metadata và các thông tin khác — cùng với isOwner.

Tạo Model#

POST /api/models

Python SDK: client.models.create(body=...)

Tạo một bản ghi model chưa được huấn luyện để bạn có thể gắn weights vào hoặc huấn luyện model.

Phản hồi (201): id, owner, project, model, region.

Cập nhật Model#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

Các trường được chấp nhận gồm name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError và starred. Chỉ truyền projectId sẽ chuyển model sang một dự án khác thuộc cùng chủ sở hữu; phản hồi trả về slug của model trong dự án đích, renamed: true nếu slug đó đã được sử dụng tại dự án đích và 409 khi model vẫn đang được huấn luyện.

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

metadata tùy chỉnh tách biệt với các trường do quá trình huấn luyện quản lý như trainArgs, environment và trainResults, đồng thời sử dụng cùng giới hạn kích thước như metadata tập dữ liệu.

Xóa model#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

Chuyển model vào thùng rác trong 30 ngày và xóa vĩnh viễn mọi deployment sử dụng model đó, bao gồm cả các deployment đang chờ thay thế. Khôi phục model không khôi phục các deployment.

Tải xuống tệp Model#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

Trả về các URL đã ký có thời hạn ngắn cho weights của model.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

Tìm ảnh tương tự với các ảnh validation có kết quả kém nhất#

GET /api/models/{owner}/{project}/{model}/similar-images

Python SDK: client.models.find_similar_training_images(owner, project, model)

Trả về tối đa 100 images, có cấu trúc giống Tìm ảnh tương tự, trông giống các ảnh validation mà lần chạy huấn luyện này chấm điểm thấp nhất, ngoại trừ những ảnh đã có trong tập dữ liệu huấn luyện. Truyền hashes (phân tách bằng dấu phẩy, tối đa 100) để tìm kiếm trong một tập con gồm các ảnh có kết quả kém nhất đó. Cần API key có quyền truy cập vào workspace của model. Danh sách sẽ trống nếu lần chạy không ghi lại kết quả theo từng ảnh; 404 cũng có nghĩa là ảnh kém nhất chưa được nhúng: trước tiên hãy chạy embeddings tập dữ liệu trên tập dữ liệu huấn luyện.

Clone model#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

Sao chép một model có thể truy cập vào một dự án hiện có.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

Chạy suy luận#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

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

Biểu mẫu Multipart:

Cung cấp file hoặc source. Model độ sâu cũng chấp nhận bits (8, 12 hoặc 16) để chọn phương thức lượng tử hóa PNG cho bản đồ độ sâu. Các yêu cầu vượt giới hạn đầu vào của dịch vụ sẽ trả về 413.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/predict

Phản hồi:

Mỗi mục trong images chứa shape, speed, results và, đối với các tác vụ dự đoán dày đặc, một payload PNG semantic_mask hoặc depth (giá trị độ sâu là pixel × max / divisor, với 255 làm số chia cho bản đồ 8-bit mặc định và 65535 khi bits là 12 hoặc 16). Object metadata báo cáo số lượng ảnh, tên class của model, thời gian thực thi hàm, tác vụ và phiên bản dịch vụ. Không bao giờ trả về đường dẫn model nội bộ.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "forklift"],
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Kiểm tra tiến trình huấn luyện#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

Trả về job, chứa trạng thái, tiến độ epoch, thời gian, thông tin tính toán, tham số huấn luyện, metrics theo epoch và thông tin lỗi an toàn; hoặc trả về null nếu model chưa từng được huấn luyện. Có thể đọc model trong các dự án công khai mà không cần xác thực.

Hủy huấn luyện#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

Dừng instance tính toán đang chạy và đánh dấu job là đã hủy. Trả về 409 khi quá trình huấn luyện không còn hoạt động.

API Training#

Khởi chạy quá trình huấn luyện YOLO trên GPU đám mây và theo dõi tiến độ theo thời gian thực. Xem tài liệu Cloud Training.

Lấy tình trạng khả dụng của GPU#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Trả về trạng thái nguồn cung hiện tại, được lập chỉ mục theo ID GPU. Công khai và không cần xác thực; truyền managed=true để bao gồm năng lực huấn luyện được quản lý, vốn cần API key.

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

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://acme-vision/datasets/warehouse",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

Phản hồi:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

Quá trình huấn luyện trả về 402 khi số dư tín dụng của bạn quá thấp và 503 khi không có năng lực khả dụng cho GPU được yêu cầu.

API Exports#

Chuyển đổi model sang các định dạng tối ưu như ONNX, TensorRT, CoreML và LiteRT để triển khai trên thiết bị biên. Xem tài liệu Deploy.

Liệt kê Exports#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

Tham số truy vấn:

Tạo Export#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

Mỗi định dạng chỉ sử dụng các tùy chọn trong cột Arguments của bảng export bên dưới: giá trị khác mặc định của batch, dynamic, opset, simplify, workspace hoặc optimize đối với định dạng không hỗ trợ tùy chọn đó sẽ trả về 400. Các bản export imx chỉ hỗ trợ INT8 và khả dụng cho model detect, segment, classify và pose; model YOLO26 cũng như các kích thước YOLOv8 hoặc YOLO11 khác nano sẽ trả về 400.

Phản hồi (201): id, format, status (queued hoặc running), region và gpuType đối với export TensorRT. Một export tương đương đang được xử lý sẽ trả về 409.

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

Sử dụng tham số format trong bảng export dùng chung bên dưới. PyTorch là định dạng nguồn và không phải đích export của API.

nms=None mặc định xuất đầu ra thô cho NMS bên ngoài. Đặt nms=False để chọn một head không dùng NMS hiện có; các định dạng không được hỗ trợ sẽ chuyển về luồng đầu ra gốc. Các mục nms ở trên xác định những định dạng có thể tích hợp NMS với nms=True.

Lấy trạng thái Export#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

Trả về object export với status, format, args, gpuType (chỉ TensorRT), dấu thời gian và — khi hoàn tất — object file chứa size, downloadUrl và downloadFilename.

Hủy hoặc xóa Export#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

Hủy một export đang hoạt động hoặc xóa export đã hoàn tất cùng tệp của export đó. Phản hồi cho biết thao tác nào đã được thực hiện:

{
    "success": true,
    "action": "cancelled"
}

API Deployments#

Triển khai model lên các endpoint inference chuyên dụng, có kiểm tra tình trạng và giám sát. Xem tài liệu Endpoints.

Liệt kê Deployments#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Tham số truy vấn:

Người gọi ẩn danh phải lọc theo một model công khai; để liệt kê toàn bộ workspace cần xác thực.

Tạo Deployment#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

Phần thân:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

Phản hồi (201): id, deployment, status (creating), message và region.

Lấy Deployment#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

Trả về đối tượng deployment gồm status, statusMessage, region, serviceUrl, resources và metadata tùy chỉnh, cùng camera và cameraApplying dành cho chủ sở hữu.

Cập nhật Deployment#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

Gửi một trong các body sau:

{ "name": "Edge 1 (primary)" }

Đổi tên sẽ đặt giá trị deployment trong URL thành slug từ tên mới và trả về dưới dạng deployment; đường dẫn cũ trả về 404, còn serviceUrl không thay đổi. Đối tượng metadata rỗng sẽ xóa metadata tùy chỉnh. Thay thế sẽ triển khai phiên bản mới trong khi vẫn giữ nguyên ID deployment, khu vực và URL endpoint; phiên bản hiện tại tiếp tục hoạt động nếu quá trình triển khai thất bại. Model thay thế phải là model đã hoàn tất, có weights mà API key của bạn có thể truy cập. Thao tác camera lưu camera RTSP hoặc RTSPS để endpoint sẵn sàng có tài nguyên tùy chỉnh tiếp tục chạy inference (xem Camera chạy nền); "url": null sẽ xóa camera, thao tác đổi kích thước về mặc định cũng vậy; lưu camera trên endpoint kích thước mặc định sẽ trả về 403. Thay đổi camera trả về 202 với status ready trong khi thay đổi được áp dụng: truy vấn deployment cho đến khi cameraApplying không còn là true, sau đó kiểm tra camera; nếu thay đổi thất bại, camera trước đó vẫn được giữ và statusMessage được thiết lập. Các thao tác đã hoàn tất trả về 200 với status ready hoặc stopped; các thao tác khác vẫn đang triển khai sẽ trả về 202 với deploying hoặc stopping.

Xóa Deployment#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

Xóa vĩnh viễn inference endpoint.

Kiểm tra tình trạng#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

Gửi ping và làm nóng endpoint, trả về healthy, latencyMs và mã status từ upstream.

Chạy inference trên Deployment#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

Định tuyến hình ảnh hoặc video qua endpoint chuyên dụng. Hợp đồng request và response tương ứng với inference model. Luồng camera không được proxy; hãy gửi luồng đến URL endpoint như mô tả trong Inference từ camera trực tiếp.

Biểu mẫu Multipart:

Lấy metrics#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

Tham số truy vấn:

Response đầy đủ chứa summary (tổng số request, tỷ lệ lỗi, độ trễ trung bình và p50/p95/p99) và timeSeries (request, lỗi, độ trễ, CPU, bộ nhớ, số lượng instance). Response sparkline trả về requests24h (số lượng request theo giờ; các giờ không có request sẽ bị lược bỏ), totalRequests, errorRate và avgLatencyMs (trung bình độ trễ P95 theo giờ). Với view=overview, summary chứa totalRequests, errorRate, và p95LatencyMs, còn timeSeries chứa requests, errors và latencyP95.

Lấy logs#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

Tham số truy vấn:

API Agents#

Lưu và quản lý các quy trình làm việc của Agents. API lưu các định nghĩa agent; các lượt chạy bắt đầu từ canvas Agents, trong đó https://platform.ultralytics.com/agents?workflow={id} mở agent đã lưu. Các phương thức Python SDK cần ultralytics-platform>=0.1.74.

Mỗi thao tác chấp nhận tham số query owner không bắt buộc, chứa tên người dùng của workspace mà bạn là thành viên (mặc định: workspace của bạn). Việc liệt kê cần quyền viewer; lưu và xóa cần quyền editor.

Liệt kê Agents#

GET /api/workflows

Python SDK: client.agents.list()

Response liệt kê tối đa 100 agent trong workflows, theo thứ tự cập nhật gần đây nhất, mỗi agent có id, username, name, version, createdAt và updatedAt. Yêu cầu id cũng trả về graph của agent.

Lưu agent#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

Gửi version: 0 để tạo agent. Để cập nhật agent, gửi id cùng version được trả về trong lần liệt kê hoặc lưu gần nhất; version đã cũ sẽ trả về 409, vì vậy hãy liệt kê lại agent rồi thử lại. Đồ thị có các kết nối tạo thành chu trình hoặc khiến một block có nhiều hơn một đầu vào sẽ trả về 400.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

Response trả về agent id, version mới của agent và errors: các block mà canvas sẽ đánh dấu, chẳng hạn như block Dataset chưa chọn dataset nào. Dù thế nào agent cũng được lưu. Xem openapi.json để biết mọi loại block và cấu hình của từng loại.

Xóa agent#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

Xóa agent và hủy các lượt chạy đang hoạt động của agent. Agent đã xóa sẽ không xuất hiện trong Thùng rác và không thể khôi phục.

API Thùng rác#

Xem, khôi phục và xóa vĩnh viễn các project, dataset và model đã xóa mềm. Các mục sẽ tự động bị xóa hẳn sau 30 ngày. Xem tài liệu Thùng rác.

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

GET /api/trash

Python SDK: client.lifecycle.trash()

Tham số truy vấn:

Response bao gồm items (mỗi mục có daysRemaining), total, page, limit, totalPages và summary chứa tổng số theo loại. Với id, response thay vào đó trả về resources: các model bị ảnh hưởng và deployment sẽ bị xóa vĩnh viễn.

Khôi phục mục#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Khôi phục project cũng khôi phục các model đã bị chuyển vào thùng rác cùng project, được báo cáo trong restoredModels.

Xóa vĩnh viễn#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

Xóa một mục:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Hoặc dọn sạch toàn bộ thùng rác:

{
    "all": true
}

Response báo cáo deletedCount, cùng cascadedModels và survivingDeployments khi có liên quan.

API Upload#

Upload file trực tiếp lên cloud storage bằng URL có chữ ký. Hoàn tất upload model sẽ đính kèm weights; hoàn tất upload archive dataset sẽ xác minh archive, sau đó bạn truyền session vào dataset ingest, thao tác này cũng hoàn tất upload nếu bạn bỏ qua bước đó. Xem tài liệu Data.

Lấy URL upload có chữ ký#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

Phần thân:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Phản hồi:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z",
    "headers": { "x-goog-if-generation-match": "0" }
}

Upload file bằng request PUT đến uploadUrl, sử dụng cùng Content-Type mà bạn đã khai báo và mọi header được trả về trong headers. URL upload dataset có hiệu lực trong 12 giờ và chỉ cho phép tạo mới: lần PUT thứ hai đến cùng URL sẽ trả về 412, còn PUT không kèm các header được trả về sẽ trả về 400.

Hoàn tất upload#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

Response: success và một đối tượng file có size và contentType. Với model, thao tác này đính kèm weights; với archive dataset, hãy gọi ingest tiếp theo để bắt đầu xử lý.

Nếu có md5, giá trị này sẽ được đối chiếu với đối tượng đã lưu. Nếu không khớp, hệ thống trả về 400; với session chưa hoàn tất, file đã upload cũng bị xóa và session vẫn chưa hoàn tất, vì vậy hãy yêu cầu URL có chữ ký mới rồi upload lại. Có thể hoàn tất lại session dataset đã hoàn tất khi archive vẫn tồn tại, nhưng các lần hoàn tất đồng thời với digest khác nhau sẽ trả về 409; session model sẽ bị xóa khi hoàn tất. checksum được lưu làm siêu dữ liệu file model và không được xác minh.

API tích hợp Storage#

Kết nối tài khoản Google Cloud Storage, Amazon S3 hoặc Azure Blob Storage ở chế độ chỉ đọc và duyệt nội dung như các nguồn dataset. Xem tài liệu Integrations.

Việc khám phá và kết nối storage cần quyền quản trị workspace và gói Pro hoặc Enterprise (403 nếu không đáp ứng điều kiện này); liệt kê integration và duyệt object cần quyền editor.

Liệt kê integration#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Trả về integrations, mỗi mục có id, provider, credentialIdentity, targets và createdAt. Thông tin xác thực không bao giờ được trả về.

Khám phá vị trí#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

Liệt kê các bucket hoặc container có thể đọc được bằng thông tin xác thực đã cung cấp mà không lưu thông tin đó.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

Phản hồi: {"targets": ["my-bucket", "another-bucket"]}

Kết nối storage#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

Có cùng cấu trúc thông tin xác thực như thao tác khám phá, đồng thời yêu cầu mảng targets gồm 1-50 tên bucket hoặc container. Trả về 201 có integration đã lưu. Thông tin xác thực S3 tạm thời (các access key ASIA) bị từ chối.

Duyệt object#

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

Python SDK: client.storage_integrations.objects(id, target=...)

Tham số truy vấn:

Trả về entries (mỗi kind là folder hoặc file) và cursor tùy chọn cho trang tiếp theo.

Ngắt kết nối storage#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

Xóa thông tin xác thực đã lưu mà không xóa dữ liệu của provider. Các dataset đã kết nối vẫn hiển thị, nhưng file của chúng sẽ không khả dụng cho đến khi kết nối lại cùng tài khoản storage. Cần quyền quản trị workspace.

API nhập dataset#

Nhập dataset từ các dịch vụ bên thứ ba. Xem tích hợp Roboflow.

Xem trước thao tác nhập từ Roboflow#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

Dùng API key Roboflow để tạo kế hoạch nhập: thông tin workspace, newDatasets sẽ được nhập, số lượng project đã nhập trước đó (skippedCount), không có phiên bản, không được hỗ trợ và chưa phân giải, bytesTotal, cùng dung lượng còn lại storage của bạn. API key Roboflow được đọc từ body và không được lưu lại.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Nhập từ Roboflow#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

Đưa vào hàng đợi các job ingest cho tối đa 500 phiên bản project Roboflow đã chọn, sử dụng các mục được trả về khi xem trước.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

Response (201): các mảng imported, failed và skipped. Việc nhập cần dung lượng storage còn trống, và mỗi dataset phải nằm trong giới hạn kích thước mỗi lần nhập của gói.

API tài khoản#

Kiểm tra tài khoản Platform, key, storage và hồ sơ công khai của bạn. Xem tài liệu Settings.

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

GET /api/account/summary

Python SDK: client.account.summary()

Trả về gói, số dư credit và số lượng tài nguyên của workspace đã cấp key.

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

Liệt kê API key#

GET /api/api-keys

Python SDK: client.account.api_keys()

Trả về keys cùng keyId, name, keyPrefix và createdAt cho workspace của key. Request được xác thực bằng API key chỉ nhận metadata; chủ workspace có thể xem đầy đủ giá trị key trong Settings > API Keys trên giao diện người dùng Platform; đây cũng là nơi tạo và thu hồi key.

Kiểm tra mức sử dụng storage#

GET /api/storage

Python SDK: client.account.storage()

Tham số truy vấn:

Phản hồi:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

usage báo cáo số lượng của projects, datasets, models, images, annotations và deployments, cùng số byte của storage. limit có giá trị -1 nghĩa là không giới hạn, còn percent là phần trăm nguyên của giới hạn.

Lấy hồ sơ người dùng công khai#

GET /api/users

Python SDK: client.account.profile(username=...)

Tham số truy vấn:

Trả về hồ sơ công khai user với followerCount và, với bên gọi đã xác thực, isFollowed.

Theo dõi hoặc bỏ theo dõi người dùng#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

Response: followed và followerCount đã cập nhật.

API thanh toán#

Kiểm tra mức sử dụng gói và sổ cái tín dụng của bạn. Xem tài liệu Thanh toán.

Xem gói và mức sử dụng#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

Trả về plan (ID, trạng thái, chu kỳ thanh toán, thời điểm kết thúc kỳ), metrics (giới hạn và mức sử dụng dung lượng lưu trữ), trainingCredit, features, creditsCents và số lượng seat.

Xem giao dịch#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Tham số truy vấn:

Mỗi giao dịch bao gồm id, type (chẳng hạn như purchase, training, monthly_grant hoặc refund), amountCents, balanceAfter, createdAt, receiptUrl tùy chọn và ngữ cảnh model cho các khoản phí huấn luyện. Chi tiết thanh toán nội bộ không bao giờ được trả về.

Khám phá API#

Tìm kiếm các project và dataset công khai do cộng đồng chia sẻ, hoặc tìm kiếm hình ảnh theo nội dung hiển thị. Xem tài liệu Explore.

Tìm kiếm nội dung công khai#

GET /api/explore/search

Python SDK: client.explore.search()

Tham số truy vấn:

Response: projects, datasets và hasMore. type=images thay vào đó trả về các kết quả khớp trong images, theo thứ tự khớp tốt nhất trước; mỗi kết quả có dataset nguồn và score độ tương đồng từ 0–1. Tham số này yêu cầu q và tìm kiếm trong các dataset công khai, cũng như dataset cá nhân và dataset nhóm của bạn nếu bạn gửi API key.

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

Python SDK#

ultralytics-platform là client Python có kiểu dữ liệu, được tạo từ hợp đồng OpenAPI, với một phương thức cho mỗi endpoint (client.datasets.list, client.models.predict, client.exports.create, ...). Mỗi phương thức nhận tham số đường dẫn theo vị trí, các đầu vào khác dưới dạng đối số từ khóa, và timeout cùng extra_headers tùy chọn cho từng request.

pip install "ultralytics-platform>=0.1.45" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # đọc ULTRALYTICS_API_KEY hoặc key được lưu bằng yolo login
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform cung cấp cùng cây tài nguyên cho mã async/await; phản hồi không thành công sẽ phát sinh APIError kèm theo status_code, body và json đã phân tích; lỗi kết nối sẽ phát sinh APIConnectionError. Xem kho SDK để đọc toàn bộ README.

Tích hợp Python#

Đối với quy trình huấn luyện và inference, hãy sử dụng package Python của Ultralytics; package này tự động xử lý xác thực, tải lên và truyền metric theo thời gian thực. Trên Python 3.11 trở lên, pip install ultralytics cũng cài đặt SDK ultralytics-platform. Khi model.train(project=...) nhắm đến Platform, các callback huấn luyện truyền sự kiện thông qua client.training.metrics() của SDK và yêu cầu URL tải checkpoint lên thông qua client.models.upload_checkpoint(), các thao tác POST /api/webhooks/training/metrics và POST /api/webhooks/models/upload trong tài liệu OpenAPI, vì vậy bạn không cần tự gọi.

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

Tích hợp Platform yêu cầu Python>=3.11 và ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

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 trên Platform#

Tham chiếu dataset bằng URI ul://:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Huấn luyện trên dataset Platform của bạn
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Định dạng URI:

Đẩy lên Platform#

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

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Kết quả tự động đồng bộ với Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

Nội dung được đồng bộ:

• Metric huấn luyện (theo thời gian thực)
• Trọng số model cuối cùng
• Biểu đồ validation
• Đầu ra console
• Metric hệ thống
• Tham số huấn luyện và môi trường máy chủ (tên máy chủ, hệ điều hành, Python, phần cứng, commit git, dòng lệnh)

Ví dụ API#

Tải model từ Platform:

# Model của riêng bạn
model = YOLO("ul://username/project/model-name")

# Model chính thức
model = YOLO("ul://ultralytics/yolo26/yolo26n")

Chạy inference:

results = model("image.jpg")

# Truy cập kết quả
for r in results:
    boxes = r.boxes  # Các bounding box phát hiện
    masks = r.masks  # Các mask phân đoạn
    keypoints = r.keypoints  # Các keypoint pose
    probs = r.probs  # Xác suất phân loại

Export model:

# Xuất sang ONNX
model.export(format="onnx", imgsz=640, quantize=16)

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

# Export sang CoreML
model.export(format="coreml", imgsz=640)  # dùng imgsz=224 cho phân loại

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#