Tham chiếu REST API#

Ultralytics Platform cung cấp REST API để truy cập theo chương trình vào các tập dữ liệu, hình ảnh, dự án, model, quá trình huấn luyện, xuất dữ liệu và triển khai.

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

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 các endpoint đều yêu cầu API key. Các endpoint hiển thị nội dung công khai — đọc tập dữ liệu, dự án hoặc model công khai, liệt kê hình ảnh tập dữ liệu công khai, chạy suy luận trên một model công khai hoặc tìm kiếm trong Explore — cũng chấp nhận các yêu cầu ẩn danh và chỉ đơn giản là trả về nhiều dữ liệu hơn khi cung cấp key.

Nhận API Key#

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

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

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

Bao gồm API key của bạn 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ả các API endpoint sử dụng:

https://platform.ultralytics.com/api

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

Tài nguyên được định địa chỉ bằng chính các tên dễ đọc đối với con người xuất hiện trong các URL của Platform, chứ 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 không gian làm việc của nhóm: 4-32 ký tự, chữ và số viết thường có dấu gạch ngang đơn giữa các phân đoạn.
• {dataset}, {project}, {model} và {deployment} tuân theo cùng một mẫu chữ thường phân tách bằng dấu gạch ngang, tối đa 128 ký tự.
• {imageId} và {exportId} là các ID thập lục phân có độ dài 24 ký tự do API trả về.
• Đổi tên tài nguyên thông qua PATCH sẽ thay đổi cả tên hiển thị name và tên URL cùng lúc, và phản hồi sẽ trả về tên URL hiện tại để bạn có thể tiếp tục theo dõi.

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

API thực thi các giới hạn cửa sổ trượt (sliding-window) cho mỗi API key. Mỗi route thuộc về một danh mục và mỗi danh mục có một bộ đếm độc lập, do đó 20 yêu cầu dự đoán sẽ không làm tiêu tốn định 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 và quản lý nhóm, có giới hạn riêng không áp dụng cho lưu lượng truy cập bằng API key.

Khi bị điều tiết (throttled), API sẽ trả về 429 kèm theo 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)#

Dedicated endpoints không tuân theo giới hạn tốc độ API-key của Platform khi bạn gọi trực tiếp serviceUrl của bản triển khai (ví dụ: https://predict-abc123.run.app/predict). Thông lượng sau đó sẽ phụ thuộc vào cấu hình dịch vụ đã triển khai.

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

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

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

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

Các phản hồi mang dữ liệu cũng bao gồm region (us, eu hoặc ap), là vùng lưu trữ cho không gian làm việc đó.

Phản hồi lỗi#

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

{
    "error": "Dataset not found"
}

Phân trang#

Kiểu phân trang phụ thuộc vào tập hợp:

Datasets API#

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

Liệt kê Datasets#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

Trả về các tập dữ liệu công khai của chủ sở hữu, cộng với các tập dữ liệu riêng tư khi key của bạn có quyền xem không gian làm việc đó.

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

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

Phản hồi (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ề đối tượng tập dữ liệu đầy đủ dưới khóa dataset, bao gồm classNames, splits, versions, source và đối tượng metadata do người dùng định nghĩa.

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 (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 (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 và starred. Gửi một đối tượng metadata trống ({}) để xóa siêu dữ liệu tùy chỉnh. Các khóa siêu dữ liệu được giới hạn ở 128 ký tự và đối tượng được tuần tự hóa giới hạn ở 500.000 ký tự.

Phản hồi (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 yêu cầu tiếp theo.

Xóa Dataset#

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

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

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

Sao chép (Clone) Dataset#

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

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

Sao chép một tập dữ liệu có thể truy cập, cùng với hình ảnh và nhãn của tập dữ liệu đó, vào không gian làm việc cá nhân hoặc không gian làm việc nhóm của bạn.

Body tùy chọn (tất cả các 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. Các tập dữ liệu được hỗ trợ bởi nguồn lưu trữ được kết nối sẽ trả về 409 vì các tệp của chúng không bị sao chép.

Tải xuống bản xuất tập dữ liệu#

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

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

Trả về một URL tải xuống NDJSON đã được ký. Bỏ qua v để xuất trạng thái hiện tại của tập dữ liệu, tái sử dụng bản xuất được lưu vào bộ nhớ đệm khi không có gì thay đổi kể từ khi nó được tạo.

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

Phản hồi (Response):

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

Yêu cầu một phiên bản cụ thể 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 bản chụp (snapshot) được đánh số không thể thay đổi của tập dữ liệu và lưu trữ tệp xuất NDJSON của bản đó. Yêu cầu quyền truy cập chỉnh sửa.

Phần thân (tùy chọn):

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

Phản hồi (Response):

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

reused là true khi tập dữ liệu không thay đổi kể từ phiên bản trước và bản chụp đó được trả về thay thế.

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=...)

Body:

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

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

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

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

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

Tái tạo lại các hình ảnh, chú thích và lớp từ phiên bản đã lưu mà không cần sao chép các byte hình ảnh.

Body:

{
    "version": 2
}

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

Lấy Thống Kê Tập Dữ Liệu#

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 hình ảnh và chú thích, cùng với bản đồ nhiệt (heatmap). Các tập dữ liệu lớn sẽ được lấy mẫu, trong trường hợp đó sampleSize sẽ báo cáo số lượng hình ảnh đã đóng góp.

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

Hợp nhất các lớp (gán lại các chú thích cho một lớp mục tiêu, 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 các lớp (các chú thích của chúng bị xóa và ID các lớp còn lại dịch chuyển xuống dưới):

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 với bản tóm tắt những gì đã thay đổi (mergedClassIds và targetClassId, hoặc deletedClassIds và deletedAnnotations).

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

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

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

Phân bổ lại ngẫu nhiên các hình ảnh giữa các tập chia tách (splits). Ba tỷ lệ phần trăm phải tổng cộng bằng 100.

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

Phản hồi: success, số lượng kết quả splits, và modified (số lượng hình ảnh đã di chuyển).

Embeddings tập dữ liệu#

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ề tóm tắt phân tích (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST xếp hàng đợi phân tích embedding và trả về 202 kèm theo jobId. DELETE hủy tác vụ đang chạy và trả về ID tác vụ đã hủy hoặc null.

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

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

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

Trả về bố cục UMAP 2D từ một phân tích đã hoàn thành, được phân trang với offset và limit (mặc định và tối đa 50.000). Mỗi mục có id, umapX, umapY, split, classIds, width, height, bytes, labelCount, và missing.

Liệt Kê Các Model Được Đào Tạo Trên Tập Dữ Liệu#

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

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

Phản hồi (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ê Hình Ảnh Tập Dữ Liệu#

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

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

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

Phản hồi (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 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 hình dạng hình ảnh cho tối đa 1.000 ID hình ảnh được cung cấp, và chấp nhận các tham số truy vấn URL và bộ lọc giống như thao tác liệt kê.

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

Nạp Dữ Liệu Vào Tập Dữ Liệu#

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 lưu trữ từ xa (remote archive), hoặc một nguồn lưu trữ được kết nối vào một tập dữ liệu hiện có. Cung cấp chính xác một nguồn:

Các phiên tải lên được liên kết với một tập dữ liệu bằng assetId được truyền tới POST /api/upload/signed-url, và tính năng nạp dữ liệu sẽ từ chối phiên thuộc về một tập dữ liệu khác.

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

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

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

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

Phần thân (nhập nhãn trong lần nạp dữ liệu sau):

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

Phần thân (đính kèm metadata cho mỗi hình ả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 tệp lưu trữ, bao gồm cả thư mục. Đối với các tệp nhập NDJSON, mỗi bản ghi có thể mang đối tượng metadata của riêng nó, đối tượng này có ưu tiên cao hơn mục nhập imageMetadata khớp. Đường dẫn lưu trữ được giới hạn ở 1.024 ký tự, khóa metadata cấp cao nhất ở 128 ký tự, và mỗi đối tượng metadata — cũng như toàn bộ bản đồ imageMetadata — được giới hạn ở 500.000 ký tự được tuần tự hóa.

Phản hồi (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 Hình Ảnh#

Kiểm tra, chú thích, di chuyển và xóa hình ảnh tập dữ liệu bằng ID hình ảnh 24 ký tự của chúng. Xem Tài liệu chú thích.

Lấy Hình Ảnh#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

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

Cập Nhật Hình Ảnh#

PATCH /api/images/{imageId}

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

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

Phần thân (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] }
    ]
}

Phần thân (metadata):

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

Xóa hình ảnh#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

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

Tự Động Chú Thích Hình Ảnh#

POST /api/images/{imageId}/predict

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

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

Phản hồi: success, predictions (các đối tượng chú thích), modelUsed, và inferenceTime. Model có các lớp không khớp với tập dữ liệu sẽ trả về 422.

Di Chuyển Hàng Loạt Hình Ảnh#

PATCH /api/images/bulk

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

Di chuyển tối đa 1.000 hình ảnh từ tập dữ liệu này sang một tập chia tách 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 cho toàn bộ giỏ (basket-wide) là skip, keep_both, hoặc replace. Phản hồi báo cáo modifiedCount, skippedCount, và targetSplit.

Xóa Hàng Loạt Hình Ảnh#

DELETE /api/images/bulk

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

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

Xóa tối đa 1.000 hình ảnh từ một tập dữ liệu duy nhất và trả về deletedCount và deletedImageIds.

Lấy URL Hình ảnh Đã 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 ID hình ảnh từ một tập dữ liệu.

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

Phản hồi: urls và thumbnails, cả hai đều được khóa theo ID hình ảnh.

Projects API#

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

Liệt kê Project#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

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

Lấy Project#

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

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

Trả về đối tượng project, mảng models chứa các bản tóm tắt theo từng model (trạng thái, chỉ số, số epoch, weights, tham số huấn luyện), và isOwner.

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.

Cập nhật Project#

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 đối tượng metadata trống ({}) để xóa nó. Metadata dự án sử dụng cùng giới hạn 128 ký tự cho khóa và 500.000 ký tự cho đối tượng được tuần tự hóa như metadata tập dữ liệu.

Xóa Project#

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

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

Di chuyển dự án và các model của dự án vào thùng rác, trả về cascadedModels.

Clone Dự án#

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

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

Nhân bản (clone) một dự án có thể truy cập và các model đã hoàn thành của dự án đó. Phần thân tùy chọn chấp nhận project, name, description, visibility, license, và điểm đến owner.

API Models#

Quản lý các model YOLO đã được huấn luyện — xem các chỉ số, tải xuống weights, chạy suy luận và theo dõi quá trình huấn luyện. Xem Tài liệu model.

Liệt Kê Các Model Trong Một Dự Án#

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

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

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

Lấy Model#

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

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

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

Phản hồi mặc định chứa đối tượng model — trạng thái, tác vụ, các chỉ số, trainArgs, trainResults, classNames, computeCost, metadata, và nhiều 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 mà bạn có thể đính kèm weights vào hoặc tiến hành huấn luyện.

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 bao gồm name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError, và starred.

{
    "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ác giới hạn kích thước giống 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 mô hình vào thùng rác trong vòng 30 ngày.

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

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

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

Trả về các URL có chữ ký có thời hạn ngắn cho trọng số của mô hình.

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

Sao chép (Clone) Model#

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

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

Sao chép một mô hình 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 Inference#

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

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

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

Multipart Form:

Cung cấp file hoặc source. Các mô hình độ sâu cũng chấp nhận bits (8, 12, hoặc 16) để chọn lượng tử hóa PNG của bản đồ độ sâu. Các yêu cầu vượt quá 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 (Response):

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 tải trọng PNG semantic_mask hoặc depth (các giá trị độ sâu là pixel × max / divisor, với ước số 255 cho bản đồ 8-bit mặc định và 65535 khi bits là 12 hoặc 16). Đối tượng metadata báo cáo số lượng hình ảnh, thời gian thực thi, tác vụ và phiên bản dịch vụ. Các đường dẫn mô hình 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 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 trình epoch, thời gian, chi tiết tính toán, tham số huấn luyện, số liệu epoch và chi tiết lỗi an toàn, hoặc null khi mô hình chưa từng được huấn luyện. Các mô hình trong dự án công khai có thể đọc 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)

Chấm dứt phiên bản tính toán đang chạy và đánh dấu công việc đã bị 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 trình trong thời gian thực. Xem Tài liệu Huấn luyện Đám mây.

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 trạng thái khả dụng của GPU#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Trả về trạng thái kho hàng hiện tại được khóa bằng ID GPU. Công khai và không cần xác thực; truyền managed=true để bao gồm dung lượng huấn luyện được quản lý, vốn yêu cầu khóa API.

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

{
    "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ó dung lượng cho GPU được yêu cầu.

API Xuất#

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

Danh sách Xuất#

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

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

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

Tạo Xuất#

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

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

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

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

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

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

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

Trả về đối tượng export với status, format, args, gpuType, dấu thời gian và — sau khi hoàn thành — đối tượng file chứa size, downloadUrl và downloadFilename.

Hủy hoặc Xóa Bản xuất#

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

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

Hủy một bản xuất đang hoạt động hoặc xóa một bản xuất đã hoàn thành cùng với tệp của nó. Phản hồi báo cáo kết quả đã xảy ra:

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

API Deployments#

Triển khai mô hình tới các điểm cuối suy luận chuyênδ dụng với các kiểm tra trạng thái và giám sát. Xem Tài liệu Điểm cuối.

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 bản triển khai#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

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

Người gọi ẩn danh phải lọc theo một mô hình công khai; việc liệt kê toàn bộ không gian làm việc yêu cầu xác thực.

Tạo bản triển khai#

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

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

Lấy bản triển khai#

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

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

Trả về đối tượng deployment với status, statusMessage, region, serviceUrl và resources.

Khởi động, Dừng hoặc Thay thế một Triển khai#

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

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

Một trường action duy nhất chọn thao tác:

{ "action": "start" }

Việc thay thế sẽ triển khai một phiên bản sửa đổi mới trong khi vẫn giữ nguyên ID triển khai, khu vực và URL điểm cuối; phiên bản sửa đổi hiện tại vẫn hoạt động nếu việc triển khai thất bại. Mô hình thay thế phải là một mô hình đã hoàn thành với trọng số mà khóa của bạn có thể truy cập. Các hoạt động hoàn thành trả về 200 với status ready hoặc stopped; các hoạt động vẫn đang triển khai trả về 202 với deploying hoặc stopping.

Xóa bản triển khai#

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

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

Xóa vĩnh viễn điểm cuối suy luận.

Kiểm tra tình trạng#

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

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

Gửi tín hiệu ping và làm nóng điểm cuối, trả về healthy, latencyMs và mã status thượng nguồn.

Chạy Suy luận trên một Triển khai#

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

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

Định tuyến hình ảnh hoặc video qua điểm cuối chuyên dụng. Các hợp đồng yêu cầu và phản hồi khớp với suy luận mô hình.

Multipart Form:

Lấy số liệu#

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

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

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

Phản hồi đầy đủ chứa summary (tổng số yêu cầu, tỷ lệ lỗi, độ trễ trung bình và p50/p95/p99) và timeSeries (yêu cầu, lỗi, độ trễ, CPU, bộ nhớ, số lượng phiên bản). Phản hồi biểu đồ thu nhỏ trả về requests24h, totalRequests, errorRate và avgLatencyMs.

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

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

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

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

API Thùng rác#

Xem, khôi phục và xóa vĩnh viễn các dự án, tập dữ liệu và mô hình đã bị xóa mềm. Các mục được xóa tự động 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 (Query Parameters):

Phản hồi bao gồm items (mỗi cái có daysRemaining), total, page, limit, totalPages và summary với 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"
}

Khôi phục một dự án cũng khôi phục các mô hình đã bị đưa vào thùng rác cùng với nó, được báo cáo là 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 làm trống toàn bộ thùng rác:

{
    "all": true
}

Phản hồi báo cáo deletedCount, cộng với cascadedModels và survivingDeployments khi có liên quan.

API Tải lên#

Tải tệp trực tiếp lên bộ nhớ đám mây bằng cách sử dụng các URL có chữ ký. Việc hoàn tất quá trình tải lên mô hình sẽ đính kèm trọng số của nó; việc hoàn tất quá trình tải lên lưu trữ tập dữ liệu sẽ ghi lại phiên, mà sau đó bạn chuyển cho quá trình nạp tập dữ liệu. Xem Tài liệu Dữ liệu.

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

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
}

Phản hồi (Response):

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

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.

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

POST /api/upload/complete

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

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

Phản hồi: success và đối tượng file với size và contentType. Đối với các mô hình, thao tác này đính kèm trọng số; đối với các tệp lưu trữ tập dữ liệu, hãy gọi nạp dữ liệu tiếp theo để bắt đầu xử lý.

API Tích hợp Bộ nhớ#

Kết nối các tài khoản Google Cloud Storage, Amazon S3 hoặc Azure Blob Storage chỉ đọc và duyệt qua chúng như các nguồn tập dữ liệu. Xem Tài liệu Tích hợp.

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

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Trả về integrations, mỗi cái 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 đượ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"
    }
}

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

Kết nối Bộ nhớ#

POST /api/integrations/buckets

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

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

Duyệt qua Đối tượng#

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

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

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

Trả về entries (mỗi kind là folder hoặc file) và một 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 làm mất dữ liệu của nhà cung cấp. Các tập dữ liệu được kết nối vẫn hiển thị, nhưng các tệp của chúng vẫn không khả dụng cho đến khi cùng một tài khoản bộ nhớ được kết nối lại. Yêu cầu quyền truy cập quản trị viên không gian làm việc.

API Nhập Tập dữ liệu#

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

Xem trước một quy trình nhập Roboflow#

POST /api/integrations/roboflow/preview

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

Giải quyết khóa API Roboflow thành kế hoạch nhập: chi tiết workspace, newDatasets sẽ được nhập, số lượng dự án bị bỏ qua, không được hỗ trợ và chưa được giải quyết, bytesTotal, và hạn mức storage của bạn. Khóa API Roboflow được đọc từ phần body và không được lưu giữ.

{
    "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 tác vụ lấy dữ liệu cho tối đa 500 phiên bản dự án 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ữ trống, và mỗi tập dữ liệu phải phù hợp với giới hạn kích thước mỗi lần nhập trong gói của bạn.

API 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 cài đặt.

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

GET /api/account/summary

Python SDK: client.account.summary()

Trả về gói, số dư tín dụng và số lượng tài nguyên cho 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ê các API Keys#

GET /api/api-keys

Python SDK: client.account.api_keys()

Trả về keys với keyId, name, keyPrefix, và createdAt cho workspace của khóa. Các yêu cầu được xác thực bằng khóa API chỉ nhận siêu dữ liệu; các giá trị khóa đầy đủ được hiển thị cho chủ sở hữu workspace trong Cài đặt > Khóa API trên Giao diện Platform, đây cũng là nơi tạo và thu hồi khóa.

Kiểm tra Mức sử dụng Lưu trữ#

GET /api/storage

Python SDK: client.account.storage()

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

Phản hồi (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ố truy vấn (Query Parameters):

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

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 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 gian kết thúc kỳ), metrics (giới hạn lưu trữ và mức sử dụng), trainingCredit, features, creditsCents, và số lượng chỗ ngồi.

Xem Giao dịch#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

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

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, một receiptUrl tùy chọn, và ngữ cảnh mô hình 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ề.

API Khám phá (Explore)#

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

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

GET /api/explore/search

Python SDK: client.explore.search()

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

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à một Python client có kiểu dữ liệu được tạo từ contract 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 đều nhận các 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à các tham số tùy chọn theo từng request timeout và extra_headers.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    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ây tài nguyên tương tự cho mã async/await, các phản hồi không thành công sẽ raise ngoại lệ APIError kèm theo status_code, body, và json đã phân tích cú pháp, trong khi các lỗi kết nối sẽ raise APIConnectionError. Xem kho lưu trữ SDK để biết 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 Ultralytics Python, tính năng này xử lý tự động việc xác thực, tải lên và phát trực tuyến chỉ số thời gian thực.

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

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 (dataset) của Platform#

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

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

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

Định dạng URI:

Đẩy dữ liệu lên Platform#

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

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

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

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

Ví dụ về API#

Tải model từ Platform:

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

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

Chạy suy luận (inference):

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

Xuất model:

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

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

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

Xác thực (Validation):

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

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

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