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 (Mục Khóa API)
2. Nhấp 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 YOUR_API_KEY

Ví dụ

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

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
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 YOUR_API_KEY" },
});
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ế:

• Theo khóa API — Giới hạn được áp dụng cho mỗi khóa API trên các yêu cầu đã 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ụ, 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.

Các điểm cuối chuyên dụng (Không giới hạn)

Các đ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/predict) đi trực tiếp đến dịch vụ chuyên dụng của bạn mà không bị giới hạn tốc độ từ Nền tảng. Bạn đang trả tiền cho điện toán, vì vậy bạn nhận được thông lượng không giới hạn lên đến cấu hình mở rộng của điểm cuối của bạn.

Đị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": "Dataset not found"
}

API Tập dữ liệu

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 mô hình YOLO. Xem tài liệu về Tập dữ liệu.

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

GET /api/datasets

Tham số truy vấn:

curl -H "Authorization: Bearer YOUR_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 một bản sao của tập dữ liệu với 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 nhân bản.

Nội dung (tất cả các trường 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 bản xuất dữ liệu mới nhất.

Tham số truy vấn:

Phản hồi:

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

Tạo Phiên bản Tập dữ liệu

POST /api/datasets/{datasetId}/export

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

Nội dung yêu cầu:

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

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

Phản hồi:

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

Mô tả phiên bản cập nhật

PATCH /api/datasets/{datasetId}/export

Cập nhật mô tả của phiên bản hiện có. Chỉ dành cho chủ sở hữu.

Nội dung yêu cầu:

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

Phản hồi:

{
    "ok": 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:

Nạ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 hoặc TAR đã tải lên, bao gồm .tar.gz và .tgz, chứa hình ảnh và nhãn.

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

Hình ảnh tập 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 hàng loạt trên ảnh

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ình ảnh hàng loạt:

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

API Dự án

Hãy sắp xếp các mô hình của bạn thành các dự án. Mỗi mô hình thuộc về một dự án. Xem tài liệu về Dự án để biết thêm chi tiết .

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

Sao chép dự á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ý những người được đào tạo YOLO Mô hình — xem số liệu, tải xuống trọng số, chạy suy luận và xuất sang các định dạng khác. Xem tài liệu về Mô hình .

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.

Sao chép mô hình

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 YOUR_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

Phóng YOLO Huấn luyện trên GPU đám mây (RTX 4090, A100, H100) và theo dõi tiến độ theo thời gian thực. Xem tài liệu Huấn luyện trên đá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 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

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": "yolo26n.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

Triển khai các mô hình đến các điểm cuối suy luận chuyên dụng với tính năng tự động điều chỉnh tỷ lệ, kiểm tra tình trạng và giám sát. Xem tài liệu về Điểm cuối.

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

Các chỉ số 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 mô hình sang các định dạng tối ưu hóa như ONNX, TensorRT, CoreML và TFLite để triển khai trên thiết bị biên. Xem tài liệu Triển khai.

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 YOUR_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

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

Xem nhật ký hoạt động gần đây trên tài khoản của bạn — các buổi tập luyện, tải lên, v.v. Xem tài liệu về Hoạt động .

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

Xem và khôi phục các mục đã xóa. Các mục sẽ bị xóa vĩnh viễn sau 30 ngày. Xem tài liệu hướng dẫn về Thùng rác .

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

Kiểm tra số dư tín dụng, mua tín dụng, xem lịch sử giao dịch và cấu hình tự động nạp tiền. Xem tài liệu 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 để mua 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ý.

Tự động bổ sung

Tự động thêm tín dụng khi số dư giảm xuống dưới ngưỡng.

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ữ

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

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

Tải trực tiếp tệp lên bộ nhớ đám mây bằng URL đã ký để truyền tải nhanh chóng và đáng tin cậy. Quy trình gồm hai bước: lấy URL đã ký, sau đó tải tệp lên. Xem tài liệu về Dữ liệu .

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

Tải lên hoàn tất

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

Quản lý khóa API của bạn để truy cập lập trình. Xem tài liệu về 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 YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

API Đội ngũ & 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 về Nhóm.

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 và duyệt các bộ dữ liệu và dự án công khai được cộng đồng chia sẻ. Xem tài liệu Khám phá .

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

GET /api/explore/search

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

Quản lý hồ sơ, khóa API, dung lượng lưu trữ và cài đặt quyền riêng tư dữ liệu của bạn. Xem tài liệu Hướng dẫn 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 thành quy trình giới thiệu (đặt vùng dữ liệu, tên người dùng).

API GDPR

Yêu cầu xuất toàn bộ dữ liệu của bạn hoặc xóa vĩnh viễn tài khoản. Xem tài liệu Cài đặt .

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("yolo26n.pt")

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

Định dạng URI:

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

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

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ộ 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/datasets/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 YOUR_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 YOUR_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ải lên mô hình tự động. Bạn cũng có thể khám phá tất cả các điểm cuối một cách tương tác tại ultralytics .

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 2 tháng trước ✏️ Cập nhật 4 ngày trước

Bình luận