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#

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

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

Body:

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

Response: {"ok": true}

Khôi phục Version của Dataset#

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

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

Tái tạo ảnh, annotation và class từ một version đã lưu mà không sao chép byte ảnh.

Body:

{
    "version": 2
}

Response: {"version": 2, "imageCount": 1000}

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 annotation theo từng class, histogram ảnh và annotation, cùng heatmap. Dataset lớn được sampling; trong trường hợp đó, sampleSize báo cáo số ảnh đã đóng góp.

Response (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ý Class#

Gộp class (gán lại annotation vào class đích, sau đó xóa các class 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 class (annotation của chúng bị xóa và ID của các class còn lại được dịch chuyển xuống):

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

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 các ảnh giữa các split. Ba phần trăm phải có tổng bằng 100.

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

Response: success, số lượng splits kết quả và modified (số ảnh đã được 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 xếp hàng một phân tích embedding và trả về 202 cùng một jobId. DELETE hủy job đang hoạt động và trả về ID job đã 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ề layout 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 50.000). Mỗi entry có id, umapX, umapY, split, classIds, width, height, bytes, labelCount và missing.

Liệt kê Model được Training trên Dataset#

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

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

Response:

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

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

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

Tham số Query:

Response:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "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 các hình ảnh đã chọn#

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

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

Trả về cùng cấu trúc hình ảnh cho tối đa 1.000 image ID được cung cấp và chấp nhận cùng các tham số truy vấn bộ lọc và URL như operation list.

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

Nạp dữ liệu dataset#

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

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

Xử lý một upload đã hoàn tất, một archive từ xa hoặc một nguồn storage đã kết nối vào một dataset hiện có. Cung cấp chính xác một nguồn:

Các phiên upload được liên kết với một dataset bằng assetId được truyền tới POST /api/upload/signed-url, và thao tác ingest từ chối một phiên thuộc về dataset khác.

Body (archive đã upload):

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

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

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

Body (import label trong một lần ingest sau):

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

Body (đính kèm metadata theo từng image):

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

Các key metadata phải khớp với path đã chuẩn hóa bên trong archive, bao gồm cả các thư mục. Đối với import NDJSON, mỗi record có thể mang theo object metadata riêng, object này được ưu tiên hơn entry imageMetadata tương ứng. Path trong archive bị giới hạn ở 1.024 ký tự, key metadata cấp cao nhất ở 128 ký tự, và mỗi object metadata — cũng như toàn bộ map imageMetadata — ở 500.000 ký tự đã tuần tự hóa.

Response (201):

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

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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

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

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/{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 Images#

Kiểm tra, annotate, di chuyển và xóa image dataset theo image ID gồm 24 ký tự. Xem tài liệu Annotation.

Lấy Image#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

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

Cập nhật Image#

PATCH /api/images/{imageId}

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

Thay thế hoặc annotation hoặc metadata tùy chỉnh — gửi một trong hai dạng, không gửi cả hai.

Body (annotation):

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

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Xóa vĩnh viễn một image và các annotation của image đó.

Tự động annotate Image#

POST /api/images/{imageId}/predict

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

Chạy suy luận YOLO trên image và trả về các annotation dự đoán. Các annotation này không được lưu — ghi kết quả trở lại bằng PATCH /api/images/{imageId} khi bạn đã thấy phù hợp.

Response: success, predictions (các object annotation), modelUsed và inferenceTime. Model có các class không khớp với dataset sẽ trả về 422.

Tự động gán nhãn tập dữ liệu#

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

Python SDK: client.datasets.create_batch(owner, dataset, model_id=...)

Lưu một phiên bản tập dữ liệu, sau đó xếp hàng một lượt chạy gán nhãn cho các ảnh chưa có nhãn của tập dữ liệu bằng model và trả về 202. Phần body nhận các trường modelId, confidence và iou giống như endpoint đơn ảnh, cộng thêm includeAnnotated (mặc định là false) để cũng gán nhãn cho các ảnh đã có nhãn và một mảng classMapping tùy chọn cung cấp chỉ số lớp tập dữ liệu cho mỗi lớp model, hoặc null để bỏ qua việc đó. Các nhãn hiện có không bao giờ bị thay đổi và lượt chạy sẽ được tính phí cho các ảnh mà lượt chạy thực sự xử lý. 402 nghĩa là số dư không đủ chi trả cho ước tính, 409 nghĩa là tập dữ liệu chưa sẵn sàng, không còn ảnh nào để gán nhãn hoặc đã có một lượt chạy đang diễn ra, và 422 nghĩa là tập dữ liệu không có lớp nào: hãy tạo các lớp bằng endpoint các lớp trước khi gọi endpoint này, đó là thao tác mà bước Map classes của ứng dụng thực hiện trước khi bắt đầu một 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 thi và tiến độ của lượt chạy, hoặc lượt chạy hoàn thành gần nhất cho đến khi bị ẩn đi; DELETE (client.datasets.delete_batch(owner, dataset)) hủy một lượt chạy đang thực thi hoặc thanh toán số dư và ẩn bản tóm tắt đã hoàn thành.

Di chuyển hàng loạt Image#

PATCH /api/images/bulk

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

Di chuyển tối đa 1.000 image từ một dataset sang một split khác.

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

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

Xóa hàng loạt Image#

DELETE /api/images/bulk

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

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

Xóa tối đa 1.000 image khỏi một dataset duy nhất và trả về deletedCount cùng deletedImageIds.

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

POST /api/images/urls

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

Trả về các URL có chữ ký tạm thời cho tối đa 100 image ID từ một dataset.

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

Response: urls và thumbnails, cả hai đều được lập chỉ mục theo image ID.

API Projects#

Tổ chức các model vào project. Mỗi model thuộc về một project. Xem tài liệu Projects.

Liệt kê Projects#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

Tham số Query:

Lấy Project#

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

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

Trả về object project, mảng models gồm các bản tóm tắt theo từng model (status, metrics, epoch, weight, train args), và isOwner.

Tạo dự án#

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

Response (201): id, owner, project, region.

Cập nhật Project#

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

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

Các field đượ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 project sử dụng cùng giới hạn key 128 ký tự và object được tuần tự hóa 500.000 ký tự như metadata dataset.

Xóa dự án#

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

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

Di chuyển project và các model của project vào thùng rác, đồng thời trả về cascadedModels.

Clone dự án#

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

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

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

API Models#

Quản lý các model YOLO đã train — xem metrics, download weight, chạy suy luận và theo dõi quá trình training. Xem tài liệu Models.

Liệt kê Models trong một Project#

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

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

Tham số Query:

Lấy Model#

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

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

Tham số Query:

Response mặc định chứa object model — status, task, metrics, trainArgs, trainResults, classNames, computeCost, metadata và các trường khác — cùng với isOwner.

Tạo Model#

POST /api/models

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

Tạo một record model chưa train để bạn có thể gắn weight hoặc train model đó.

Response (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 bao gồm name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError, và starred. Việc truyền projectId đơn lẻ sẽ di chuyển model sang một dự án khác của cùng một chủ sở hữu; phản hồi trả về slug của model ở đích, renamed: true khi chuỗi định danh đó đã bị chiếm dụng ở đó, và 409 trong khi model vẫn đang huấn luyện.

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

metadata tùy chỉnh tách biệt với các field do training 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 dataset.

Xóa model#

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

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

Di chuyển model vào thùng rác trong 30 ngày.

Download File Model#

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

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

Trả về các URL có chữ ký tồn tại trong thời gian ngắn cho weight của model.

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

Nhân bản 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 project hiện có.

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

Chạy inference#

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

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

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 API key có quyền truy cập vào project cha.

Multipart Form:

Cung cấp file hoặc source. Các model depth cũng chấp nhận bits (8, 12 hoặc 16) để chọn lượng tử hóa PNG của depth map. Các request vượt quá giới hạn đầu vào của service 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

Response:

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

{
    "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,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Kiểm tra tiến trình training#

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 trình epoch, thông tin thời gian, chi tiết tính toán, tham số train, metric theo epoch và chi tiết lỗi an toàn; hoặc null khi model chưa từng được train. Có thể đọc các model trong project 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)

Kết thúc compute instance đang chạy và đánh dấu job là đã hủy. Trả về 409 khi quá trình training không còn hoạt động.

Training API#

Khởi chạy training YOLO trên cloud GPU và theo dõi tiến trình theo thời gian thực. Xem tài liệu Cloud Training.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../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

Lấy thông tin GPU khả dụng#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Trả về trạng thái tài nguyên hiện tại, được lập chỉ mục theo ID GPU. Công khai và không yêu cầu xác thực; truyền managed=true để bao gồm capacity training được quản lý, tính năng này yêu cầu API key.

Bắt đầu training#

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

Response:

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

Training trả về 402 khi số dư credit của bạn quá thấp và 503 khi không có capacity cho GPU được yêu cầu.

Exports API#

Chuyển đổi model sang các format được tối ưu như ONNX, TensorRT, CoreML và LiteRT để triển khai trên edge. Xem tài liệu Deploy.

Liệt kê các export#

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

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

Tham số Query:

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

Response (201): id, format, status (queued hoặc running), gpuType, region. Một export tương đương đang được thực hiện sẽ trả về 409.

Các format được hỗ trợ:

Sử dụng tham số format từ bảng export dùng chung bên dưới. PyTorch là format nguồn và không phải target export của API.

nms=None mặc định sử dụng đầu ra thô cho NMS bên ngoài. Thiết lập nms=False để chọn phần đầu không có NMS khả dụng; các định dạng không được hỗ trợ sẽ quay lại đường dẫn đầu ra gốc của chúng. Các mục nms ở trên xác định các định dạng có thể nhúng NMS bằng 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, các timestamp và — khi hoàn tất — mộ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 file của nó. Response cho biết thao tác nào đã xảy ra:

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

Deployments API#

Deploy model lên các inference endpoint chuyên dụng với health check và tính năng monitoring. Xem tài liệu Endpoints.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action 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 deployment#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

Tham số Query:

Caller ẩn danh phải lọc theo một model công khai; việc liệt kê toàn bộ workspace yêu cầu xác thực.

Tạo deployment#

POST /api/deployments/{owner}

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

Body:

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

Response (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ề object deployment với status, statusMessage, region, serviceUrl và resources.

Khởi động, dừng hoặc thay thế deployment#

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

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

Một field action duy nhất sẽ chọn thao tác:

{ "action": "start" }

Thao tác thay thế sẽ triển khai revision mới trong khi giữ nguyên deployment ID, region và endpoint URL; revision hiện tại vẫn 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 với weights mà key của bạn có quyền truy cập. Các thao tác đã hoàn tất trả về 200 cùng status, ready hoặc stopped; các thao tác vẫn đang triển khai trả về 202 cùng 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.

Health Check#

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

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

Ping và warm endpoint, trả về healthy, latencyMs và code upstream status.

Chạy inference trên deployment#

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

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

Định tuyến ảnh hoặc video qua endpoint chuyên dụng. Contract của request và response khớp với model inference.

Multipart Form:

Lấy metric#

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

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

Tham số Query:

Response đầy đủ chứa summary (tổng số request, tỷ lệ lỗi, latency trung bình và p50/p95/p99) và timeSeries (request, lỗi, latency, CPU, memory, số lượng instance). Response sparkline trả về requests24h, totalRequests, errorRate và avgLatencyMs.

Lấy log#

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

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

Tham số Query:

Trash API#

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

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

GET /api/trash

Python SDK: client.lifecycle.trash()

Tham số Query:

Response bao gồm items (mỗi mục chứa daysRemaining), total, page, limit, totalPages và summary chứa tổng số theo loại.

Khôi phục mục#

POST /api/trash

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

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

Việc khôi phục một project cũng khôi phục các model đã bị đưa vào trash cùng project đó, được báo cáo dưới dạng 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 xóa toàn bộ trash:

{
    "all": true
}

Response báo cáo deletedCount, cùng cascadedModels và survivingDeployments khi phù hợp.

Upload API#

Upload file trực tiếp lên cloud storage bằng signed URL. Khi hoàn tất upload model, weights của model sẽ được gắn vào; khi hoàn tất upload dataset archive, session sẽ được ghi nhận, sau đó bạn truyền session này vào dataset ingest. Xem tài liệu Data.

Lấy URL upload đã ký#

POST /api/upload/signed-url

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

Body:

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

Response:

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

Tải tệp lên bằng yêu cầu PUT tới uploadUrl, sử dụng cùng Content-Type mà bạn đã khai báo và mọi tiêu đề được trả về trong headers. Các URL tải lên dataset có hiệu lực trong 12 giờ và chỉ dành cho việc tạo: yêu cầu PUT thứ hai đến cùng một URL trả về 412, và yêu cầu PUT không có các tiêu đề đã 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 object file với size và contentType. Đối với model, thao tác này sẽ gắn weights; đối với dataset archive, tiếp theo hãy gọi ingest để bắt đầu xử lý.

Khi md5 được cung cấp, nó được kiểm tra đối với đối tượng được lưu trữ. Sự không khớp sẽ trả về 400; trên một phiên chưa hoàn tất, người dùng cũng xóa tệp đã tải lên và để lại phiên chưa hoàn tất, do đó hãy yêu cầu một URL đã ký mới và tải lên lại. Một phiên dataset đã hoàn tất có thể được hoàn tất lại trong khi kho lưu trữ của nó tồn tại, nhưng các lần hoàn tất cạnh tranh với các mã băm khác nhau sẽ trả về 409; các phiên model sẽ bị xóa khi hoàn tất. checksum được lưu trữ dưới dạng siêu dữ liệu tệp model và không được xác thực.

Storage Integrations API#

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

Liệt kê tích hợp#

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í lưu 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 bằng thông tin xác thực được cung cấp mà không lưu chúng.

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

Response: {"targets": ["my-bucket", "another-bucket"]}

Kết nối bộ nhớ#

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ư khi khám phá, cùng với mảng targets bắt buộc gồm 1–50 tên bucket hoặc container. Trả về 201 với thông tin tích hợp đã lưu. Thông tin xác thực S3 tạm thời (các khóa truy cập ASIA) bị từ chối.

Duyệt đối tượng#

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

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

Tham số Query:

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 bộ nhớ#

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 nhà cung cấp. Các dataset đã kết nối vẫn hiển thị, nhưng tệp của chúng vẫn không khả dụng cho đến khi kết nối lại cùng tài khoản lưu trữ. Yêu cầu 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 quá trình nhập từ Roboflow#

POST /api/integrations/roboflow/preview

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

Phân giải khóa API Roboflow thành kế hoạch nhập: thông tin workspace, newDatasets sẽ được nhập, số lượng project bị bỏ qua, không được hỗ trợ và không thể phân giải, bytesTotal, cùng dung lượng còn lại storage của bạn. Khóa API 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=...)

Xếp hàng các job nhập dữ liệu cho tối đa 500 phiên bản project Roboflow đã chọn, sử dụng các mục được trả về từ bản xem trước.

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

Phản hồi (201): Các mảng imported, failed và skipped. Việc nhập yêu cầu đủ dung lượng lưu trữ 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, khóa, bộ nhớ 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 khóa.

{
    "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 khóa. Các yêu cầu được xác thực bằng API key chỉ nhận metadata; giá trị đầy đủ của khóa được hiển thị cho chủ sở hữu workspace trong Settings > API Keys trên giao diện Platform, nơi cũng dùng để tạo và thu hồi khóa.

Kiểm tra mức sử dụng bộ nhớ#

GET /api/storage

Python SDK: client.account.storage()

Tham số Query:

Response:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "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"
}

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

GET /api/users

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

Tham số Query:

Trả về hồ sơ công khai user cùng followerCount và, đối với caller đã 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
}

Phản hồi: 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 credit 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 bộ nhớ), trainingCredit, features, creditsCents và số lượng seat.

Xem giao dịch#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

Tham số Query:

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í training. Thông tin 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 được cộng đồng chia sẻ. Xem tài liệu Khám phá.

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

GET /api/explore/search

Python SDK: client.explore.search()

Tham số Query:

Phản hồi: projects, datasets và hasMore.

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, được tạo từ contract OpenAPI, với một method cho mỗi endpoint (client.datasets.list, client.models.predict, client.exports.create, ...). Mỗi method nhận các tham số path theo vị trí, các đầu vào khác dưới dạng đối số keyword, 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:  # reads ULTRALYTICS_API_KEY or the key saved by 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 code async/await, các phản hồi không thành công sẽ phát sinh APIError cùng status_code, body và json đã được phân tích, còn lỗi kết nối sẽ phát sinh APIConnectionError. Xem kho lưu trữ SDK để đọc README đầy đủ.

Tích hợp Python#

Đối với các quy trình huấn luyện và suy luận, hãy sử dụng gói Python Ultralytics, tự động xử lý việc xác thực, tải lên và phát trực tuyến số liệu theo thời gian thực. Trên Python 3.11+, pip install ultralytics cũng cài đặt SDK ultralytics-platform. Khi model.train(project=...) nhắm mục tiêu vào Platform, các callback huấn luyện sẽ phát trực tuyến các sự kiện thông qua client.training.metrics() của SDK và yêu cầu các URL tải lên điểm kiểm tra thông qua các thao tác client.models.upload_checkpoint(), 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ó gì phải tự gọi.

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

Việc tích hợp nền tảng 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 Dataset trên Platform#

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

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Định dạng URI:

Đẩy lên Platform#

Gửi kết quả đến một project 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",
)

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

• Metric training (theo thời gian thực)
• Trọng số model cuối cùng
• Biểu đồ validation
• Output trên console
• Metric hệ thống
• Các đối 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, git commit, dòng lệnh)

Ví dụ 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 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

Export 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

Validation:

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

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

FAQ#