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

Nền tảng Ultralytics cung cấp một REST API toàn diện để truy cập theo chương 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

Tổng quan về API

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

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

Xác thực

Hầu hết các yêu cầu API đều yêu cầu xác thực thông qua khóa API. Các điểm cuối công khai (liệt kê các tập dữ liệu, dự án và mô hình công khai) hỗ trợ truy cập đọc ẩn danh mà không cần khóa.

Lấy Khóa API

1. Đi đến Settings > Profile (Phần Khóa API)
2. Nhấp chuột Create Key
3. Sao chép khóa đã tạo

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

Tiêu đề ủy quyền

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

Authorization: Bearer ul_your_api_key_here

Ví dụ

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

URL cơ sở

Tất cả các điểm cuối API sử dụng:

https://platform.ultralytics.com/api

Giới hạn tốc độ

API sử dụng hệ thống giới hạn tốc độ hai lớp để ngăn chặn việc lạm dụng trong khi vẫn đảm bảo việc sử dụng hợp pháp không bị hạn chế:

• Mỗi khóa API — Giới hạn được áp dụng cho mỗi khóa API đối với các yêu cầu đã được xác thực.
• Theo địa chỉ IP — 100 yêu cầu/phút cho mỗi địa chỉ IP trên tất cả các thiết bị. /api/* đường dẫn (áp dụng cho cả yêu cầu đã xác thực và chưa xác thực)

Khi bị giới hạn tốc độ, API sẽ trả về 429 với siêu dữ liệu thử lại:

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

Giới hạn cho mỗi khóa API

Giới hạn tỷ lệ truy cập được áp dụng tự động dựa trên điểm cuối được gọi. Các thao tác tốn nhiều tài nguyên có giới hạn chặt chẽ hơn để ngăn chặn lạm dụng, trong khi các thao tác CRUD tiêu chuẩn có giới hạn mặc định khá rộng rãi:

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

Điểm cuối chuyên dụng (Không giới hạn)

Điểm cuối chuyên dụng là không chịu giới hạn số lượng khóa API.Khi bạn triển khai một mô hình đến một điểm cuối chuyên dụng, các yêu cầu đến URL điểm cuối đó (ví dụ: https://predict-abc123.run.app/predictBạn sẽ truy cập trực tiếp vào dịch vụ chuyên dụng của mình mà không bị giới hạn tốc độ từ Nền tảng. Bạn chỉ trả tiền cho năng lực tính toán, vì vậy bạn sẽ có thông lượng không giới hạn tùy thuộc vào cấu hình mở rộng của điểm cuối.

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

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

Phản hồi trả về JSON với các trường dành riêng cho từng tài nguyên:

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

Phản hồi lỗi

{
    "error": "Invalid dataset ID"
}

API Tập dữ liệu

Quản lý các bộ sưu tập hình ảnh đã được gắn nhãn phục vụ mục đích đào tạo. YOLO mô hình.

Liệt kê bộ dữ liệu

GET /api/datasets

Tham số truy vấn:

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

Phản hồi:

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

Lấy Tập dữ liệu

GET /api/datasets/{datasetId}

Trả về đầy đủ thông tin chi tiết của tập dữ liệu, bao gồm siêu dữ liệu, tên lớp và số lượng phân tách.

Tạo Tập dữ liệu

POST /api/datasets

Nội dung:

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

Cập nhật tập dữ liệu

PATCH /api/datasets/{datasetId}

Nội dung (cập nhật một phần):

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

Xóa bộ dữ liệu

DELETE /api/datasets/{datasetId}

Xóa mềm tập dữ liệu (chuyển vào thùng rác , có thể khôi phục trong vòng 30 ngày).

Sao chép Tập dữ liệu

POST /api/datasets/{datasetId}/clone

Tạo bản sao của tập dữ liệu bao gồm tất cả hình ảnh và nhãn. Chỉ các tập dữ liệu công khai mới có thể được sao chép.

Nội dung (tất cả các trường đều tùy chọn):

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

Xuất Tập dữ liệu

GET /api/datasets/{datasetId}/export

Trả về phản hồi JSON với URL tải xuống đã được ký cho tệp xuất dữ liệu.

Phản hồi:

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

Nhận số liệu thống kê lớp học

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

Trả về phân bố lớp, bản đồ nhiệt vị trí và số liệu thống kê về kích thước. Kết quả được lưu vào bộ nhớ đệm trong tối đa 5 phút.

Phản hồi:

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

Huấn luyện mô hình trên tập dữ liệu

GET /api/datasets/{datasetId}/models

Trả về các mô hình được huấn luyện bằng tập dữ liệu này.

Phản hồi:

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

Tự động chú thích tập dữ liệu

POST /api/datasets/{datasetId}/predict

Chạy YOLO Thực hiện suy luận trên ảnh trong tập dữ liệu để tự động tạo chú thích. Sử dụng mô hình đã chọn để dự đoán nhãn cho các ảnh chưa được chú thích.

Nội dung:

Nhập tập dữ liệu

POST /api/datasets/ingest

Tạo một tác vụ nhập dữ liệu để xử lý các tệp ZIP đã tải lên chứa hình ảnh và nhãn.

graph LR
    A[Upload ZIP] --> B[POST /api/datasets/ingest]
    B --> C[Process ZIP]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

Hình ảnh bộ dữ liệu

Liệt kê hình ảnh

GET /api/datasets/{datasetId}/images

Tham số truy vấn:

Lấy URL hình ảnh đã ký

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

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

Xóa hình ảnh

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

Lấ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ể.

Cập nhật nhãn hình ảnh

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

Nội dung:

{
    "labels": [{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] }]
}

Thao tác xử lý hình ảnh hàng loạt

Di chuyển hình ảnh giữa các tập dữ liệu (huấn luyện/kiểm tra/thử nghiệm):

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

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

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

API Dự án

Quản lý không gian làm việc đào tạo nhóm các mô hình lại với nhau.

Liệt kê Dự án

GET /api/projects

Tham số truy vấn:

Lấy Dự án

GET /api/projects/{projectId}

Tạo dự án

POST /api/projects

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

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

Cập nhật dự án

PATCH /api/projects/{projectId}

Xóa Dự án

DELETE /api/projects/{projectId}

Xóa dự án một cách nhẹ nhàng (chuyển vào thùng rác ).

Dự án nhân bản

POST /api/projects/{projectId}/clone

Biểu tượng dự án

Tải lên biểu tượng dự án (biểu mẫu nhiều phần với tệp hình ảnh):

POST /api/projects/{projectId}/icon

Xóa biểu tượng dự án:

DELETE /api/projects/{projectId}/icon

API Mô hình

Quản lý các điểm kiểm tra mô hình đã được đào tạo trong các dự án.

Liệt kê Mô hình

GET /api/models

Tham số truy vấn:

Liệt kê các mô hình đã hoàn thành

GET /api/models/completed

Trả về các mô hình đã hoàn thành quá trình huấn luyện (để sử dụng trong bộ chọn mô hình và triển khai).

Lấy Mô hình

GET /api/models/{modelId}

Tạo mô hình

POST /api/models

Nội dung JSON:

Cập nhật mô hình

PATCH /api/models/{modelId}

Xóa mô hình

DELETE /api/models/{modelId}

Tải xuống các tệp mô hình

GET /api/models/{modelId}/files

Trả về các URL tải xuống đã ký cho các tệp mô hình.

Mô hình nhân bản

POST /api/models/{modelId}/clone

Sao chép một mô hình công khai vào một trong các dự án của bạn.

Nội dung:

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

Tải xuống bài hát

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

Theo dõi số liệu phân tích lượt tải xuống mô hình.

Chạy suy luận

POST /api/models/{modelId}/predict

Biểu mẫu đa phần:

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

Phản hồi:

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

Nhận mã thông báo dự đoán

POST /api/models/{modelId}/predict/token

Nhận mã thông báo có thời hạn ngắn để thực hiện các yêu cầu dự đoán trực tiếp. Mã thông báo này bỏ qua máy chủ proxy API, giúp giảm độ trễ khi suy luận từ các ứng dụng phía máy khách.

Mô hình khởi động

POST /api/models/{modelId}/predict/warmup

Tải trước mô hình để tăng tốc quá trình suy luận ban đầu. Hãy gọi hàm này trước khi chạy dự đoán để tránh sự chậm trễ trong yêu cầu ban đầu.

API Huấn luyện

Khởi tạo, theo dõi và hủy các tác vụ đào tạo trên nền tảng đám mây.

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

Bắt Đầu Huấn Luyện

POST /api/training/start

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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

Lấ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, các chỉ số và tiến độ của một mô hình.

Hủy Huấn luyện

DELETE /api/models/{modelId}/training

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

AP Triển khai

Tạo và quản lý các điểm cuối suy luận chuyên dụng.

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

Liệt kê Triển khai

GET /api/deployments

Tham số truy vấn:

Tạo Triển khai

POST /api/deployments

Nội dung:

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

Tạo một điểm cuối suy luận chuyên dụng trong khu vực được chỉ định. Điểm cuối này có thể truy cập được trên toàn cầu thông qua một URL duy nhất.

Lấy Triển khai

GET /api/deployments/{deploymentId}

Xóa Triển khai

DELETE /api/deployments/{deploymentId}

Bắt đầu Triển khai

POST /api/deployments/{deploymentId}/start

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

Dừng Triển khai

POST /api/deployments/{deploymentId}/stop

Tạm dừng quá trình triển khai đang chạy (dừng tính phí).

Kiểm tra sức khỏe

GET /api/deployments/{deploymentId}/health

Trả về trạng thái sức khỏe của điểm cuối triển khai.

Chạy suy luận khi triển khai

POST /api/deployments/{deploymentId}/predict

Gửi trực tiếp hình ảnh đến điểm cuối triển khai để suy luận. Về mặt chức năng, nó tương đương với mô hình dự đoán, nhưng được định tuyến qua điểm cuối chuyên dụng để giảm độ trễ.

Biểu mẫu đa phần:

Lấy Chỉ số

GET /api/deployments/{deploymentId}/metrics

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

Tham số truy vấn:

Lấy Nhật ký

GET /api/deployments/{deploymentId}/logs

Tham số truy vấn:

API giám sát

Số liệu tổng hợp

GET /api/monitoring

Trả về các số liệu tổng hợp trên tất cả các triển khai của người dùng: tổng số yêu cầu, số lượng triển khai đang hoạt động, tỷ lệ lỗi và độ trễ trung bình.

AP Xuất

Chuyển đổi các mô hình sang định dạng tối ưu hóa cho việc triển khai tại biên.

Liệt kê Xuất

GET /api/exports

Tham số truy vấn:

Tạo Xuất

POST /api/exports

Nội dung:

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

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

Lấy Trạng thái Xuất

GET /api/exports/{exportId}

Hủy xuất khẩu

DELETE /api/exports/{exportId}

Theo dõi xuất khẩu Tải xuống

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

AP Hoạt động

track và quản lý các sự kiện hoạt động cho tài khoản của bạn.

Liệt kê Hoạt động

GET /api/activity

Tham số truy vấn:

Đánh dấu Sự kiện đã xem

POST /api/activity/mark-seen

Nội dung:

{
    "all": true
}

Hoặc truyền các ID cụ thể:

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

Lưu trữ Sự kiện

POST /api/activity/archive

Nội dung:

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

Hoặc truyền các ID cụ thể:

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

AP Thùng rác

Quản lý các tài nguyên đã xóa mềm (lưu giữ 30 ngày).

Liệt kê Thùng rác

GET /api/trash

Tham số truy vấn:

Khôi phục Mục

POST /api/trash

Nội dung:

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

Xóa vĩnh viễn mục

DELETE /api/trash

Nội dung:

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

Làm rỗ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.

API Thanh toán

Quản lý số dư tín dụng, gói đăng ký và phương thức thanh toán.

Lấy Số dư

GET /api/billing/balance

Tham số truy vấn:

Phản hồi:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

Lấ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à các chỉ số sử dụng.

Nhận giao dịch

GET /api/billing/transactions

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

Tham số truy vấn:

Tạo Phiên thanh toán

POST /api/billing/checkout-session

Nội dung:

{
    "amount": 25,
    "owner": "team-username"
}

Tạo phiên thanh toán cho giao dịch mua bằng thẻ tín dụng.

Tạo Thanh toán Đăng ký

POST /api/billing/subscription-checkout

Tạo phiên thanh toán để nâng cấp gói đăng ký Pro.

Nội dung:

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Tạo Phiên Cổng thông tin

POST /api/billing/portal-session

Trả về URL của cổng thanh toán để quản lý đăng ký.

Nạp tiền tự động

Tự động cộng thêm tiền khi số dư giảm xuống dưới một ngưỡng nhất định.

Tải cấu hình nạp tiền tự động

GET /api/billing/auto-topup

Tham số truy vấn:

Cập nhật cấu hình nạp tiền tự động

PATCH /api/billing/auto-topup

Nội dung:

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Phương thức thanh toán

Liệt kê các phương thức thanh toán

GET /api/billing/payment-methods

Tạo Intent thiết lập

POST /api/billing/payment-methods/setup

Trả về mã bí mật khách hàng để thêm phương thức thanh toán mới.

Thiết lập phương thức thanh toán mặc định

POST /api/billing/payment-methods/default

Nội dung:

{
    "paymentMethodId": "pm_123"
}

Cập nhật thông tin thanh toán

PATCH /api/billing/payment-methods

Nội dung:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Xóa phương thức thanh toán

DELETE /api/billing/payment-methods/{id}

API Lưu trữ

Lấy thông tin lưu trữ

GET /api/storage

Phản hồi:

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

Tính toán lại dung lượng lưu trữ

POST /api/storage

Kích hoạt quá trình tính toán lại dung lượng lưu trữ.

API tải lên

Việc tải tệp trực tiếp sử dụng quy trình URL đã ký hai bước.

Nhận URL tải lên đã ký

POST /api/upload/signed-url

Yêu cầu URL đã ký để tải trực tiếp tệp lên bộ nhớ đám mây. URL đã ký sẽ bỏ qua máy chủ API đối với các lần truyền tải tệp lớn.

Nội dung:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Phản hồi:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

Đã hoàn tất tải lên

POST /api/upload/complete

Thông báo cho nền tảng biết quá trình tải tệp đã hoàn tất để nền tảng có thể bắt đầu xử lý.

Nội dung:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API Khóa API

Liệt kê khóa API

GET /api/api-keys

Tạo khóa API

POST /api/api-keys

Nội dung:

{
    "name": "training-server"
}

Xóa khóa API

DELETE /api/api-keys

Tham số truy vấn:

Ví dụ:

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

API Đội ngũ & Thành viên

Quản lý sự hợp tác trong không gian làm việc với các nhóm, thành viên và người được mời.

Liệt kê các đội

GET /api/teams

Tạo nhóm

POST /api/teams/create

Nội dung:

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

Danh sách 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.

Mời thành viên

POST /api/members

Nội dung:

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

Cập nhật vai trò thành viên

PATCH /api/members/{userId}

Xóa Thành viên

DELETE /api/members/{userId}

Chuyển quyền sở hữu

POST /api/members/transfer-ownership

Thư mời

Chấp nhận lời mời

POST /api/invites/accept

Nhận thông tin mời

GET /api/invites/info

Tham số truy vấn:

Hủy lời mời

DELETE /api/invites/{inviteId}

Gửi lại lời mời

POST /api/invites/{inviteId}/resend

Khám phá API

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

GET /api/explore/search

Tham số truy vấn:

Dữ 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á.

API người dùng và cài đặt

Tìm người dùng theo tên người dùng

GET /api/users

Tham số truy vấn:

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

PATCH /api/users

Nội dung:

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

Kiểm tra tính khả dụng của tên người dùng

GET /api/username/check

Tham số truy vấn:

Cà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.).

Biểu tượng hồ sơ

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

Tải lên hoặc xóa ảnh đại diện hồ sơ.

Quy trình hội nhập

POST /api/onboarding

Hoàn tất quy trình đăng ký (thiết lập vùng dữ liệu, tên người dùng).

API GDPR

Các điểm cuối tuân thủ GDPR để xuất và xóa dữ liệu.

Nhận thông tin việc làm liên quan đến GDPR

GET /api/gdpr

Tham số truy vấn:

Trả về trạng thái công việc. Đối với các công việc xuất khẩu đã hoàn tất, phản hồi bao gồm... downloadUrl.

Bắt đầu xuất hoặc xóa quy trình

POST /api/gdpr

Nội dung:

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

Tùy chọn dành cho không gian làm việc nhóm:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Mã lỗi

Python Tích hợp

Để tích hợp dễ dàng hơn, hãy sử dụng Ultralytics Python Gói phần mềm này tự động xử lý xác thực, tải lên và truyền phát số liệu theo thời gian thực.

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

pip install ultralytics

Xác minh cài đặt:

yolo check

Xác thực

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Sử dụng tập dữ liệu nền tảng

Bộ dữ liệu tham chiếu với ul:// URI:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

Định dạng URI:

Đẩy lên nền tảng

Gửi kết quả đến dự án Nền tảng:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

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

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

• Số liệu huấn luyện (thời gian thực)
• Trọng lượng mô hình cuối cùng
• Biểu đồ xác thực
• Đầu ra bảng điều khiển
• Số liệu hệ thống

Ví dụ về API

Tải mô hình từ Nền tảng:

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

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

Chạy suy luận:

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

Mô hình xuất khẩu:

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

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

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

Validation (Kiểm định):

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

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

Webhooks

Webhooks thông báo cho máy chủ của bạn về các sự kiện của Nền tảng thông qua các lệnh gọi lại HTTP POST:

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

Làm thế nào để phân trang kết quả lớn?

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

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

Các điểm cuối Activity và Trash cũng hỗ trợ page Tham số cho phân trang theo trang:

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

Điểm cuối Tìm kiếm Khám phá 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"

Tôi có thể sử dụng API mà không cần SDK không?

Đúng vậy, tất cả các chức năng đều có sẵn thông qua REST. Python SDK là một lớp 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 mô hình.

Có thư viện client API nào không?

Hiện tại, hãy sử dụng gói Ultralytics python hoặc thực hiện các yêu cầu HTTP trực tiếp. Các thư viện client chính thức cho các ngôn ngữ khác đang được lên kế hoạch.

Làm thế nào để xử lý giới hạn tốc độ yêu cầu?

Sử dụng Retry-After Tiêu đề từ phản hồi 429 để chờ đúng khoảng thời gian:

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 Exception("Rate limit exceeded")

Làm thế nào để tìm ID của mô hình hoặc tập dữ liệu của tôi?

Mã định danh tài nguyên (Resource ID) được trả về khi bạn tạo tài nguyên thông qua API. Bạn cũng có thể tìm thấy chúng trong URL của nền tảng:

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

Sử dụng các điểm cuối của danh sách để tìm kiếm theo tên hoặc lọc theo dự án.

📅 Được tạo 1 tháng trước ✍️ Cập nhật 5 ngày trước

Bình luận