Link to this sectionTham chiếu REST API#

Ultralytics Platform cung cấp một REST API toàn diện để truy cập theo lập trình vào các tập dữ liệu, mô hình, quá trình huấn luyện và triển khai.

# List your datasets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets

Link to this sectionTổng quan về API#

API được tổ chức xung quanh các tài nguyên nền tảng cốt lõi:

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

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

Link to this sectionXác thực#

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

Link to this sectionLấy API Key#

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

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

Link to this sectionTiêu đề ủy quyền (Authorization Header)#

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

Authorization: Bearer YOUR_API_KEY

Link to this sectionVí dụ#

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

Link to this sectionBase URL#

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

https://platform.ultralytics.com/api

Link to this sectionGiới hạn tốc độ (Rate Limits)#

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

Khi bị điều tiết, API sẽ trả về mã 429 cùng với siêu dữ liệu thử lại:

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

Link to this sectionGiới hạn theo API Key#

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

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

Link to this sectionEndpoint chuyên dụng (Không giới hạn)#

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

Link to this sectionĐịnh dạng phản hồi#

Link to this sectionPhản hồi thành công#

Các phản hồi trả về JSON với các trường cụ thể cho từng tài nguyên:

{
    "datasets": [...],
    "total": 100
}

Link to this sectionPhản hồi lỗi#

{
    "error": "Dataset not found"
}

Link to this sectionDatasets API#

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

Link to this sectionLiệt kê Datasets#

GET /api/datasets

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

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

Phản hồi (Response):

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

Link to this sectionLấy Dataset#

GET /api/datasets/{datasetId}

Trả về chi tiết đầy đủ của dataset bao gồm metadata, tên lớp (class names), và số lượng phân chia (split counts).

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

Link to this sectionTạo Dataset#

POST /api/datasets

Body:

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

Phản hồi (Response):

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

Link to this sectionCập nhật Dataset#

PATCH /api/datasets/{datasetId}

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

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

Link to this sectionBiểu tượng tập dữ liệu#

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

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

Link to this sectionXóa Dataset#

DELETE /api/datasets/{datasetId}

Xóa mềm dataset (được chuyển vào thùng rác, có thể khôi phục trong 30 ngày).

Link to this sectionSao chép (Clone) Dataset#

POST /api/datasets/{datasetId}/clone

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

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

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

Link to this sectionXuất Dataset#

GET /api/datasets/{datasetId}/export

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

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

Phản hồi (Response):

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

Link to this sectionTạo Phiên bản Dataset#

POST /api/datasets/{datasetId}/export

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

Request Body:

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

Tất cả các trường đều là tùy chọn. Trường description là nhãn do người dùng cung cấp cho phiên bản này.

Phản hồi (Response):

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

Link to this sectionCập nhật Mô tả Phiên bản#

PATCH /api/datasets/{datasetId}/export

Cập nhật mô tả của một phiên bản hiện có. Thao tác này yêu cầu quyền Editor trở lên.

Request Body:

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

Phản hồi (Response):

{
    "ok": true
}

Link to this sectionKhôi phục phiên bản tập dữ liệu#

POST /api/datasets/{datasetId}/restore

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

{
    "version": 2
}

Link to this sectionLấy Thống kê Lớp (Class Statistics)#

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

Trả về phân bổ lớp, bản đồ nhiệt vị trí (location heatmap) và thống kê kích thước. Kết quả được lưu cache tối đa 5 phút.

Phản hồi (Response):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Link to this sectionQuản lý Lớp (Classes)#

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

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

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

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

Xóa các lớp:

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

{
    "classIds": [2, 4]
}

Link to this sectionPhân bổ lại Tập dữ liệu (Splits)#

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

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

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

Link to this sectionEmbeddings tập dữ liệu#

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

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

Link to this sectionPhân cụm hình ảnh#

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

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

Link to this sectionLấy các Model đã huấn luyện trên Dataset#

GET /api/datasets/{datasetId}/models

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

Phản hồi (Response):

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

Link to this sectionTự động gán nhãn Dataset (Auto-Annotate)#

POST /api/datasets/{datasetId}/predict

Chạy inference YOLO trên các hình ảnh của dataset để tự động tạo chú thích. Sử dụng một model đã chọn để dự đoán nhãn cho các hình ảnh chưa được gán nhãn.

Body:

Link to this sectionNhập liệu Dataset (Ingest)#

POST /api/datasets/ingest

Tạo một tác vụ nhập dữ liệu cho một dataset hiện có. Dataset mục tiêu luôn được truyền dưới dạng datasetId trong phần thân JSON, thay vì trong đường dẫn URL.

Phần thân yêu cầu cần có datasetId kèm theo chính xác một trong hai: sessionId (phiên tải lên của một tệp lưu trữ đã tải lên) hoặc sourceUrl (URL của tệp ZIP, TAR, TAR.GZ, TGZ hoặc NDJSON từ xa). Thêm tùy chọn targetSplit (train, val hoặc test) để ghi đè cấu trúc phân chia của tệp lưu trữ.

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

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

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

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

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

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

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

Phản hồi (Response):

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

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

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

Link to this sectionHình ảnh Dataset#

Link to this sectionLiệt kê hình ảnh#

GET /api/datasets/{datasetId}/images

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

Link to this sectionLấy hình ảnh đã chọn#

POST /api/datasets/{datasetId}/images

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

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Link to this sectionLấy URL Hình ảnh Đã ký#

POST /api/datasets/{datasetId}/images/urls

Lấy các URL đã ký cho một loạt các hash hình ảnh (để hiển thị trong trình duyệt).

Link to this sectionXóa hình ảnh#

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

Link to this sectionLấy Nhãn hình ảnh#

GET /api/datasets/{datasetId}/images/{hash}/labels

Trả về các chú thích và tên lớp cho một hình ảnh cụ thể.

Link to this sectionCập nhật Nhãn hình ảnh#

PUT /api/datasets/{datasetId}/images/{hash}/labels

Body:

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

Link to this sectionThao tác hình ảnh hàng loạt#

Di chuyển hình ảnh giữa các split (train/val/test) trong một dataset:

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

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

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

Link to this sectionProjects API#

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

Link to this sectionLiệt kê Project#

GET /api/projects

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

Link to this sectionLấy Project#

GET /api/projects/{projectId}

Link to this sectionTạo Project#

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "slug": "my-project",
    "description": "Detection experiments"
  }' \
  https://platform.ultralytics.com/api/projects

Link to this sectionCập nhật Project#

PATCH /api/projects/{projectId}

Link to this sectionXóa Project#

DELETE /api/projects/{projectId}

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

Link to this sectionClone Dự án#

POST /api/projects/{projectId}/clone

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

Link to this sectionBiểu tượng Project#

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

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

Link to this sectionAPI Models#

Quản lý các model YOLO đã huấn luyện — xem số liệu, tải trọng số (weights), chạy inference và xuất ra các định dạng khác. Xem Tài liệu về Models.

Link to this sectionLiệt kê Models#

GET /api/models

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

Link to this sectionLiệt kê các Model đã hoàn tất#

GET /api/models/completed

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

Link to this sectionLấy Model#

GET /api/models/{modelId}

Link to this sectionTạo Model#

POST /api/models

JSON Body:

Link to this sectionCập nhật Model#

PATCH /api/models/{modelId}

Link to this sectionXóa Model#

DELETE /api/models/{modelId}

Link to this sectionTải xuống các tệp Model#

GET /api/models/{modelId}/files

Trả về các URL tải xuống đã được ký cho các tệp model.

Link to this sectionSao chép (Clone) Model#

POST /api/models/{modelId}/clone

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

Body:

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

Link to this sectionTheo dõi lượt tải xuống#

POST /api/models/{modelId}/track-download

Theo dõi phân tích lượt tải xuống model.

Link to this sectionChạy Inference#

POST /api/models/{modelId}/predict

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

Multipart Form:

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

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

Phản hồi (Response):

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

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

Link to this sectionAPI Training#

Khởi chạy quá trình đào tạo YOLO trên cloud GPU (26 loại GPU từ RTX 2000 Ada đến B300) và theo dõi tiến độ theo thời gian thực. Xem tài liệu Cloud Training.

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

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

Link to this sectionBắt đầu huấn luyện#

POST /api/training/start

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

Link to this sectionLấy trạng thái khả dụng của GPU#

GET /api/training/gpu-availability

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

Link to this sectionLấy trạng thái huấn luyện#

GET /api/models/{modelId}/training

Trả về trạng thái công việc huấn luyện hiện tại, số liệu, tiến trình, thời gian, thông tin GPU và các lỗi. Các dự án công khai có thể truy cập mà không cần xác thực; các dự án riêng tư và được chia sẻ yêu cầu một API key có quyền truy cập.

Link to this sectionHủy huấn luyện#

DELETE /api/models/{modelId}/training

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

Link to this sectionAPI Deployments#

Triển khai các model đến các endpoint inference chuyên dụng với kiểm tra tình trạng và giám sát. Các bản triển khai mới sử dụng scale-to-zero theo mặc định và API chấp nhận một đối tượng resources tùy chọn. Xem Tài liệu về Endpoints.

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

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

Link to this sectionLiệt kê các bản triển khai#

GET /api/deployments

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

Link to this sectionTạo bản triển khai#

POST /api/deployments

Body:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

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

Link to this sectionLấy bản triển khai#

GET /api/deployments/{deploymentId}

Link to this sectionXóa bản triển khai#

DELETE /api/deployments/{deploymentId}

Link to this sectionBắt đầu bản triển khai#

POST /api/deployments/{deploymentId}/start

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

Link to this sectionDừng bản triển khai#

POST /api/deployments/{deploymentId}/stop

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

Link to this sectionKiểm tra tình trạng#

GET /api/deployments/{deploymentId}/health

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

Link to this sectionChạy Inference trên bản triển khai#

POST /api/deployments/{deploymentId}/predict

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

Multipart Form:

Cung cấp file hoặc source. Phản hồi sử dụng cùng hợp đồng hình ảnh và metadata như dự đoán model và không bao giờ trả về đường dẫn model nội bộ.

Link to this sectionLấy số liệu#

GET /api/deployments/{deploymentId}/metrics

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

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

Link to this sectionLấy nhật ký (logs)#

GET /api/deployments/{deploymentId}/logs

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

Link to this sectionAPI Xuất#

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

Link to this sectionDanh sách Xuất#

GET /api/exports

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

Link to this sectionTạo Xuất#

POST /api/exports

Body:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

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

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

{% set integrations_path = "../../integrations" %}

{%set integrations_path = integrations_path or "../integrations" %}

Link to this sectionLấy trạng thái xuất#

GET /api/exports/{exportId}

Link to this sectionHủy xuất#

DELETE /api/exports/{exportId}

Link to this sectionTheo dõi tải xuống bản xuất#

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

Link to this sectionAPI Hoạt động#

Xem nguồn cấp dữ liệu các hành động gần đây trên tài khoản của bạn — các lần training, lượt tải lên và nhiều hơn nữa. Xem Tài liệu hoạt động.

Link to this sectionLiệt kê hoạt động#

GET /api/activity

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

Link to this sectionĐánh dấu sự kiện đã xem#

POST /api/activity/mark-seen

Body:

{
    "all": true
}

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

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

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

Link to this sectionLưu trữ sự kiện#

POST /api/activity/archive

Body:

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

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

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

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

Link to this sectionAPI Thùng rác#

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

Link to this sectionLiệt kê thùng rác#

GET /api/trash

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

Link to this sectionKhôi phục mục#

POST /api/trash

Body:

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

Link to this sectionXóa mục vĩnh viễn#

DELETE /api/trash

Body:

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

Link to this sectionLàm trống thùng rác#

DELETE /api/trash/empty

Xóa vĩnh viễn tất cả các mục trong thùng rác.

Link to this sectionAPI Thanh toán#

Kiểm tra số dư tín dụng, mức sử dụng gói và lịch sử giao dịch của bạn. Xem Tài liệu thanh toán.

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

Link to this sectionLấy số dư#

GET /api/billing/balance

Phản hồi (Response):

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

Link to this sectionLấy tóm tắt sử dụng#

GET /api/billing/usage-summary

Trả về chi tiết gói, giới hạn và số liệu sử dụng.

Link to this sectionLấy giao dịch#

GET /api/billing/transactions

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

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

Link to this sectionAPI Lưu trữ#

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

Link to this sectionLấy Thông tin Lưu trữ#

GET /api/storage

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

Phản hồi (Response):

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

Link to this sectionTích hợp lưu trữ đám mây#

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

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

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

Link to this sectionAPI Tải lên#

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

Link to this sectionLấy Signed URL Tải lên#

POST /api/upload/signed-url

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

Body:

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

Phản hồi (Response):

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

Link to this sectionHoàn tất Tải lên#

POST /api/upload/complete

Thông báo cho nền tảng rằng việc tải lên tệp đã hoàn tất. Đối với các model, thao tác này đính kèm các trọng số đã tải lên. Đối với lưu trữ tập dữ liệu, thao tác này xác minh và ghi lại phiên tải lên; sau đó hãy gọi POST /api/datasets/ingest để bắt đầu xử lý tập dữ liệu.

Body:

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

Link to this sectionAPI Tích hợp#

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

Link to this sectionXem trước Nhập từ Roboflow#

POST /api/integrations/roboflow/preview

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

Link to this sectionNhập từ Roboflow#

POST /api/integrations/roboflow/import

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

Link to this sectionAPI API Keys#

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

Link to this sectionLiệt kê các API Keys#

GET /api/api-keys

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

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

Link to this sectionTạo API Key#

POST /api/api-keys

Body:

{
    "name": "training-server"
}

Link to this sectionXóa API Key#

DELETE /api/api-keys

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

Ví dụ:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

Link to this sectionAPI Nhóm & Thành viên#

Tạo không gian làm việc nhóm, mời thành viên và quản lý vai trò để cộng tác. Xem Tài liệu Nhóm.

Link to this sectionLiệt kê các Nhóm#

GET /api/teams

Link to this sectionTạo Nhóm#

POST /api/teams/create

Body:

{
    "username": "my-team",
    "fullName": "My Team"
}

Link to this sectionLiệt kê các Thành viên#

GET /api/members

Trả về các thành viên của không gian làm việc hiện tại.

Link to this sectionMời Thành viên#

POST /api/members

Body:

{
    "email": "user@example.com",
    "role": "editor"
}

Link to this sectionCập nhật Vai trò Thành viên#

PATCH /api/members/{userId}

Link to this sectionXóa Thành viên#

DELETE /api/members/{userId}

Link to this sectionChuyển nhượng Quyền sở hữu#

POST /api/members/transfer-ownership

Link to this sectionAPI Khám phá (Explore)#

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

Link to this sectionTìm kiếm Nội dung Công khai#

GET /api/explore/search

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

Link to this sectionDữ liệu Thanh bên#

GET /api/explore/sidebar

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

Link to this sectionAPI Người dùng & Cài đặt#

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

Link to this sectionTóm tắt tài khoản#

GET /api/account/summary

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

Link to this sectionLấy Người dùng theo Tên người dùng#

GET /api/users

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

Link to this sectionTheo dõi hoặc Bỏ theo dõi Người dùng#

PATCH /api/users

Body:

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

Link to this sectionKiểm tra tính sẵn sàng của Tên người dùng#

GET /api/username/check

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

Link to this sectionCài đặt#

GET /api/settings
POST /api/settings

Lấy hoặc cập nhật cài đặt hồ sơ người dùng (tên hiển thị, tiểu sử, liên kết mạng xã hội, v.v.).

Link to this sectionBiểu tượng không gian làm việc#

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

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

Link to this sectionTích hợp Python#

Để tích hợp dễ dàng hơn, hãy sử dụng gói Python của Ultralytics, gói này tự động xử lý việc xác thực, tải lên và phát trực tuyến các chỉ số theo thời gian thực.

Link to this sectionCài đặt & Thiết lập#

pip install "ultralytics>=8.4.104"

Xác minh cài đặt:

yolo check

Link to this sectionXác thực#

yolo settings api_key=YOUR_API_KEY

Link to this sectionSử dụng tập dữ liệu (dataset) của Platform#

Tham chiếu tập dữ liệu với 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:

Link to this sectionĐẩ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

Link to this sectionVí 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)

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

Link to this sectionCâu hỏi thường gặp#

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

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

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

Các endpoint Activity và Trash cũng hỗ trợ tham số page để phân trang theo trang:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

Endpoint Explore Search sử dụng offset thay vì page, với kích thước trang cố định là 20:

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

Link to this sectionTôi có thể sử dụng API mà không cần SDK không?#

Các thao tác REST công khai được ghi lại ở trên khả dụng mà không cần Python SDK. SDK là một trình bao bọc tiện lợi bổ sung các tính năng như truyền phát số liệu theo thời gian thực và tự động tải lên model. Bạn có thể khám phá hợp đồng máy đọc được một cách tương tác tại platform.ultralytics.com/api/docs; các luồng tài khoản chỉ dành cho phiên trình duyệt vẫn nằm trong UI Nền tảng.

Link to this sectionCó thư viện client API nào không?#

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

Link to this sectionLàm cách nào để xử lý giới hạn tốc độ (rate limit)?#

Sử dụng header Retry-After từ phản hồi 429 để đợi một khoảng thời gian hợp lý:

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise RuntimeError("Rate limit exceeded")

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

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

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

Sử dụng các endpoint danh sách để tìm _id tương ứng cho một mô hình, tập dữ liệu, dự án, bản triển khai hoặc tài nguyên khác.