Справочник REST API#

Ultralytics Platform предоставляет комплексный REST API для программного доступа к датасетам, моделям, обучению и развертыванию.

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

Обзор API#

API организован вокруг основных ресурсов платформы:

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

Аутентификация#

API ресурсов используют аутентификацию по API-key, включая управление классами и разбиением наборов данных, клонирование, обучение, экспорт, развертывание и чтение поддерживаемых данных учетной записи. Публичные эндпоинты поддерживают анонимный доступ там, где это указано. Маршруты приложений, предназначенные только для браузера, исключены.

Получение API-ключа#

1. Перейди в Settings > API Keys
2. Нажми Create Key
3. Скопируй созданный ключ

Подробные инструкции см. в разделе Ключи API.

Заголовок авторизации#

Добавляй свой API-ключ во все запросы:

Authorization: Bearer YOUR_API_KEY

Пример#

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

Базовый URL#

Все API-эндпоинты используют:

https://platform.ultralytics.com/api

Ограничения частоты запросов#

API применяет лимиты на основе скользящего окна с поддержкой Upstash Redis для каждого ключа API. Каждый маршрут использует соответствующую категорию ниже.

При ограничении частоты запросов API возвращает 429 с метаданными для повторной попытки:

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

Лимиты на API-ключ#

Ограничения применяются автоматически в зависимости от вызываемого эндпоинта. Для ресурсоемких операций установлены более жесткие лимиты, чтобы предотвратить злоупотребления, в то время как стандартные операции CRUD используют щедрый лимит по умолчанию:

Каждая категория имеет независимый счетчик для каждого API-ключа. Например, выполнение 20 запросов предсказания не влияет на твой лимит в 100 запросов/мин по умолчанию.

Выделенные эндпоинты (безлимитные)#

Выделенные эндпоинты не подпадают под ограничения частоты запросов ключа API Platform, если ты обращаешься к URL эндпоинта напрямую (например, https://predict-abc123.run.app/predict). Пропускная способность в таком случае зависит от конфигурации развернутой службы.

Формат ответа#

Успешные ответы#

Ответы возвращают JSON с полями, специфичными для ресурса:

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

Ответы об ошибках#

{
    "error": "Dataset not found"
}

API наборов данных#

Создавай, просматривай и управляй размеченными датасетами изображений для обучения моделей YOLO. См. документацию по датасетам.

Список наборов данных#

GET /api/datasets

Параметры запроса:

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

Ответ:

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

Получить набор данных#

GET /api/datasets/{datasetId}

Возвращает информацию о датасете, включая названия классов, количество сплитов и другие свойства, управляемые Platform. Пользовательские метаданные загружаются отдельно из эндпоинта метаданных ниже.

Передай username, если {datasetId} представляет собой слаг датасета, а не идентификатор.

Создать набор данных#

POST /api/datasets

Тело запроса:

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

Ответ:

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

Обновить набор данных#

PATCH /api/datasets/{datasetId}

Тело запроса (частичное обновление):

{
    "name": "Updated Name",
    "description": "New description",
    "metadata": { "location": "factory-2", "reviewed": true },
    "visibility": "public"
}

Отправь пустой объект metadata ({}), чтобы очистить пользовательские метаданные. Сериализованный объект метаданных ограничен 500 000 символов, а каждый ключ верхнего уровня ограничен 128 символами.

Получить метаданные датасета#

GET /api/datasets/{datasetId}/metadata

Возвращает объект пользовательских метаданных и специально подобранный набор доступных только для чтения пар «поле/значение», управляемых Ultralytics. Пользовательские метаданные намеренно исключены из обычных полезных данных датасета. Требуются аутентификация и доступ к рабочему пространству датасета.

Значок набора данных#

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

Загрузи иконку WebP размером до 5 МБ в качестве поля формы multipart image или удали текущую иконку.

Удалить набор данных#

DELETE /api/datasets/{datasetId}

Выполняет мягкое удаление датасета (перемещается в корзину, доступно для восстановления в течение 30 дней).

Клонирование набора данных#

POST /api/datasets/{datasetId}/clone

Создает копию публичного, принадлежащего тебе или редактируемого набора данных рабочей области со всеми изображениями и метками.

Необязательное тело запроса (все поля необязательны):

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

Экспортировать набор данных#

GET /api/datasets/{datasetId}/export

Возвращает JSON-ответ с подписанной URL-ссылкой для скачивания последней версии экспорта набора данных.

Параметры запроса:

Ответ:

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

Создать версию набора данных#

POST /api/datasets/{datasetId}/export

Создай новый нумерованный снимок версии датасета. Для этого требуется уровень доступа редактора или выше. Версия фиксирует текущее количество изображений, классов, аннотаций и распределение сплитов, после чего генерирует и сохраняет неизменяемый экспорт в формате NDJSON.

Тело запроса:

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

Все поля необязательны. Поле description — это заданная пользователем метка для версии.

Ответ:

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

Обновить описание версии#

PATCH /api/datasets/{datasetId}/export

Обнови описание существующей версии. Для этого требуется уровень доступа редактора или выше.

Тело запроса:

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

Ответ:

{
    "ok": true
}

Восстановить версию набора данных#

POST /api/datasets/{datasetId}/restore

Восстанови изображения, аннотации и классы набора данных из сохраненной версии без копирования байтов изображений.

{
    "version": 2
}

Получить статистику классов#

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

Возвращает распределение классов, тепловую карту местоположения и статистику размеров. Результаты кэшируются на срок до 5 минут.

Ответ:

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

Управление классами#

Объединение классов (переназначение аннотаций из исходных классов в целевой, затем удаление исходных):

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

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

ID классов являются позиционными, поэтому объединение не идемпотентно. Повторно получи набор данных перед повторной попыткой.

Удаление классов:

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

{
    "classIds": [2, 4]
}

Перераспределение выборок#

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

Случайным образом перераспредели изображения между обучающей, проверочной и тестовой выборками. Процентные доли в сумме должны составлять 100.

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

Эмбеддинги набора данных#

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

GET возвращает текущую сводку анализа UMAP и статус активного задания; POST ставит задание анализа эмбеддингов в очередь; DELETE отменяет активное задание.

Кластеризация изображений#

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

Возвращает 2D-макет UMAP и метаданные для каждого изображения для представления кластеризации (с разбивкой на страницы и ограничением скорости запросов).

Получить модели, обученные на наборе данных#

GET /api/datasets/{datasetId}/models

Возвращает модели, которые были обучены с использованием этого набора данных.

Ответ:

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

Автоматическая разметка набора данных#

POST /api/datasets/{datasetId}/predict

Запусти YOLO-вывод на изображениях набора данных для автоматической генерации аннотаций. Использует выбранную модель для предсказания меток для неразмеченных изображений.

Тело запроса:

Загрузка набора данных#

POST /api/datasets/ingest

Создать задачу загрузки данных для существующего датасета. Целевой датасет всегда передается как datasetId в теле JSON, а не в пути URL.

Тело запроса требует наличия datasetId плюс ровно одного из следующих параметров: sessionId (сеанс загрузки выгруженного архива) или sourceUrl (URL удаленного ZIP, TAR, TAR.GZ, TGZ или NDJSON). Добавь необязательный параметр targetSplit (train, val или test), чтобы переопределить структуру разбиения архива. Для прикрепления пользовательских метаданных используй imageMetadata, ключом в котором является точный путь каждого изображения относительно архива или значение NDJSON file.

Для загруженных архивов сеанс загрузки уже привязан к датасету с помощью assetId, переданного в POST /api/upload/signed-url; средство загрузки проверяет, что assetId соответствует datasetId в теле запроса. Необязательные элементы classMapping сопоставляют каждое входящее имя класса с существующим индексом класса, начинающимся с нуля, именем класса для повторного использования или создания либо null для пропуска класса. Для импорта удаленных sourceUrl сначала создай датасет, а затем передай его datasetId для загрузки.

Тело запроса (загруженный архив):

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

Тело запроса (одно или несколько изображений с метаданными):

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

Локальные изображения используют существующий процесс загрузки архива независимо от того, содержит ли архив одно изображение или много. Ключ должен соответствовать нормализованному пути внутри архива, включая папки. Для импорта NDJSON каждая запись изображения может вместо этого содержать собственный объект metadata. Локальная для записи metadata имеет приоритет над соответствующим элементом imageMetadata.

Метаданные представлены в формате JSON и поддерживают вложенные значения. Пути в архиве ограничены 1024 символами, ключи метаданных верхнего уровня — 128 символами, а каждый объект метаданных — 500 000 сериализованными символами. Полная карта imageMetadata или объединенные эффективные метаданные при импорте NDJSON также ограничены 500 000 сериализованными символами. Эти ограничения включены в интерактивную схему OpenAPI.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

Тело запроса (удаленный архив или NDJSON):

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

Тело (последующий прием, импорт меток):

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

Ответ:

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

Изображения набора данных#

Список изображений#

GET /api/datasets/{datasetId}/images

Параметры запроса:

Получить выбранные изображения#

POST /api/datasets/{datasetId}/images

Возвращает одну и ту же форму изображения для 1000 предоставленных ID изображений. Принимает те же параметры управления URL и метками, что и операция списка.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

Получить подписанные URL изображений#

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

Получи подписанные URL для пакета хешей изображений (для отображения в браузере).

Удалить изображение#

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

Получить метки изображения#

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

Возвращает аннотации и имена классов для конкретного изображения.

Обновить метки изображения#

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

Тело запроса:

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

Массовые операции с изображениями#

Перемещай изображения между разбиениями (train/val/test) внутри набора данных:

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

Массовое удаление изображений:

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

API проектов#

Организуй свои модели по проектам. Каждая модель принадлежит одному проекту. См. документацию по проектам.

Список проектов#

GET /api/projects

Параметры запроса:

Получить проект#

GET /api/projects/{projectId}

Создать проект#

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",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Обновить проект#

PATCH /api/projects/{projectId}

Тело запроса (частичное обновление):

{
    "metadata": { "department": "research", "program": "inspection" }
}

Отправь пустой объект metadata ({}), чтобы очистить его. Метаданные проекта используют те же ограничения на 128-символьный ключ верхнего уровня и 500 000 символов для сериализованного объекта, что и метаданные датасета.

Получить метаданные проекта#

GET /api/projects/{projectId}/metadata

Возвращает объект пользовательских метаданных и доступные только для чтения пары «поле/значение», управляемые Ultralytics. Требуются аутентификация и доступ к рабочему пространству проекта.

Удалить проект#

DELETE /api/projects/{projectId}

Выполняет мягкое удаление проекта (перемещается в корзину).

Клонировать проект#

POST /api/projects/{projectId}/clone

Клонирует общедоступный, принадлежащий вам или доступный для редактирования проект рабочего пространства и его модели в твой аккаунт или рабочее пространство. Необязательное тело JSON принимает параметры name, slug, description, visibility, license и переопределения пункта назначения owner.

Значок проекта#

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

Загрузи иконку WebP размером до 5 МБ в качестве поля формы multipart image или удали текущую иконку.

API моделей#

Управляй обученными моделями YOLO: просматривай метрики, скачивай веса, запускай инференс и экспортируй в другие форматы. См. документацию по моделям.

Список моделей#

GET /api/models

Параметры запроса:

Список завершенных моделей#

GET /api/models/completed

Возвращает до 1000 моделей с пригодными для использования весами по всем проектам для обучения и развертывания. Передай owner для рабочего пространства.

Получить модель#

GET /api/models/{modelId}

Создать модель#

POST /api/models

JSON тело:

Обновить модель#

PATCH /api/models/{modelId}

Тело запроса (частичное обновление):

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

Отправь пустой объект metadata ({}), чтобы очистить его. Пользовательские метаданные модели отделены от информации о модели, принадлежащей обучению, сведений об окружении и аргументов обучения, а также используют те же ограничения сериализованного объекта и ключей верхнего уровня, что и метаданные датасета.

Получить метаданные модели#

GET /api/models/{modelId}/metadata

Возвращает объект пользовательских метаданных и доступные только для чтения пары «поле/значение», управляемые Ultralytics. Требуются аутентификация и доступ к рабочему пространству модели.

Удалить модель#

DELETE /api/models/{modelId}

Скачать файлы модели#

GET /api/models/{modelId}/files

Возвращает подписанные URL-адреса для скачивания файлов модели.

Клонирование модели#

POST /api/models/{modelId}/clone

Клонируй публичную, принадлежащую тебе или редактируемую модель рабочей области в один из своих проектов.

Тело запроса:

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

Отслеживать скачивания#

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

Отслеживай аналитику скачиваний модели.

Запусти вывод#

POST /api/models/{modelId}/predict

Публичные модели можно использовать для предсказаний без аутентификации. Для частных и общих моделей требуется API key с доступом к родительскому проекту.

Multipart Form:

Предоставь либо file, либо source. Максимальный размер загружаемого файла составляет 100 МБ.

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

Ответ:

Ответы содержат для каждого изображения shape, speed, results и необязательные плотные данные карты пикселей (семантическую карту классов или карту глубины, где depth = pixel × max / divisor — делитель 255 для карты по умолчанию на 8 бит, 65535 с bits=12|16), а также metadata с количеством изображений, временем выполнения функции, задачей и версиями службы. Внутренние пути моделей никогда не возвращаются.

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

API обучения#

Запусти обучение YOLO на облачных GPU (26 типов GPU от RTX 2000 Ada до B300) и следи за ходом выполнения в режиме реального времени. См. документацию по облачному обучению.

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

Начать обучение#

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

Получить доступность GPU#

GET /api/training/gpu-availability

Возвращает текущий статус наличия GPU (High, Medium, Low или null), сгруппированный по идентификатору типа GPU. Общедоступно, аутентификация не требуется; кэшируется на 5 минут.

Получить статус обучения#

GET /api/models/{modelId}/training

Возвращает текущий статус задания обучения, метрики, прогресс, время, детали GPU и ошибки. Публичные проекты доступны без аутентификации; для частных и общих проектов требуется API key с доступом.

Отменить обучение#

DELETE /api/models/{modelId}/training

Завершает работу запущенного вычислительного экземпляра и помечает задание как отмененное.

API развертываний#

Развертывай модели на выделенных эндпоинтах инференса с проверкой работоспособности и мониторингом. Новые развертывания по умолчанию используют масштабирование до нуля, а API принимает необязательный объект resources. См. документацию по эндпоинтам.

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

Список развертываний#

GET /api/deployments

Параметры запроса:

Создать развертывание#

POST /api/deployments

Тело запроса:

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

Создает выделенный эндпоинт инференса в указанном регионе. Эндпоинт глобально доступен через уникальный URL.

Получить развертывание#

GET /api/deployments/{deploymentId}

Удалить развертывание#

DELETE /api/deployments/{deploymentId}

Запустить развертывание#

POST /api/deployments/{deploymentId}/start

Возобновить остановленное развертывание.

Остановить развертывание#

POST /api/deployments/{deploymentId}/stop

Останови обработку запросов, установив минимальное и максимальное количество инстансов сервиса равным нулю.

Проверка работоспособности#

GET /api/deployments/{deploymentId}/health

Возвращает статус работоспособности эндпоинта развертывания.

Запустить инференс на развертывании#

POST /api/deployments/{deploymentId}/predict

Отправь изображение напрямую на эндпоинт развертывания для инференса. Функционально эквивалентно предсказанию модели, но маршрутизируется через выделенный эндпоинт для уменьшения задержки.

Multipart Form:

Предоставь либо file, либо source. Ответ использует тот же контракт изображения и метаданных, что и предсказание модели, и никогда не возвращает внутренний путь модели.

Получить метрики#

GET /api/deployments/{deploymentId}/metrics

Возвращает количество запросов, задержку и показатели частоты ошибок с данными спарклайна.

Параметры запроса:

Получить логи#

GET /api/deployments/{deploymentId}/logs

Параметры запроса:

API экспорта#

Конвертируй модели в оптимизированные форматы, такие как ONNX, TensorRT, CoreML и LiteRT, для развертывания на периферийных устройствах (edge). См. документацию по развертыванию.

Список экспортов#

GET /api/exports

Параметры запроса:

Создать экспорт#

POST /api/exports

Тело запроса:

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

Поддерживаемые форматы:

Используй аргумент format из общей таблицы экспорта ниже. PyTorch является исходным форматом и не является целевым форматом экспорта API.

Получить статус экспорта#

GET /api/exports/{exportId}

Отменить экспорт#

DELETE /api/exports/{exportId}

Отследить скачивание экспорта#

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

API активности#

Просматривай ленту последних действий в своем аккаунте: запусков обучения, выгрузок и многого другого. См. документацию по активности.

Список активности#

GET /api/activity

Параметры запроса:

Пометить события как просмотренные#

POST /api/activity/mark-seen

Тело запроса:

{
    "all": true
}

Или передай конкретные ID:

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

Передай необязательный параметр запроса owner, чтобы пометить события в рабочем пространстве.

Архивировать события#

POST /api/activity/archive

Тело запроса:

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

Или передай конкретные ID:

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

Передай необязательный параметр запроса owner, чтобы архивировать или восстановить события рабочего пространства.

API корзины#

Просматривай и восстанавливай удаленные элементы. Элементы удаляются навсегда через 30 дней. См. документацию по корзине.

Список корзины#

GET /api/trash

Параметры запроса:

Восстановить элемент#

POST /api/trash

Тело запроса:

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

Безвозвратно удалить элемент#

DELETE /api/trash

Тело запроса:

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

Очистить корзину#

DELETE /api/trash/empty

Безвозвратно удаляет все элементы в корзине.

API биллинга#

Проверяй баланс средств, использование тарифного плана и историю транзакций. См. документацию по биллингу.

Эндпоинты баланса и транзакций принимают необязательный параметр запроса owner с именем пользователя владельца рабочего пространства.

Получить баланс#

GET /api/billing/balance

Ответ:

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

Получить сводку использования#

GET /api/billing/usage-summary

Возвращает детали плана, лимиты и метрики использования.

Получить транзакции#

GET /api/billing/transactions

Возвращает историю транзакций (сначала самые новые).

Транзакции включают поля для клиента, такие как сумма, итоговый баланс, дата, необязательный контекст модели и URL квитанции. Внутренние примечания, ID платежей/возвратов Stripe и идемпотентные ключи не возвращаются.

Storage API#

Проверяй распределение использования хранилища по категориям (наборы данных, модели, экспорты) и просматривай самые большие элементы.

Получить информацию о хранилище#

GET /api/storage

Параметры запроса:

Ответ:

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

Интеграции с облачным хранилищем#

Подключайся и просматривай доступные только для чтения интеграции GCS, S3 или Azure Blob storage:

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

Все четыре операции принимают необязательный параметр запроса owner для рабочего пространства. Просмотр объектов также принимает обязательный параметр target плюс необязательные параметры запроса prefix и провайдера cursor. Тела запросов на подключение и обнаружение используют схемы учетных данных провайдера в интерактивной справке OpenAPI; учетные данные никогда не возвращаются.

Upload API#

Загружай файлы напрямую в облачное хранилище с помощью подписанных URL для быстрой и надежной передачи. Завершение загрузки модели привязывает ее веса. Завершение загрузки архива датасета регистрирует сеанс; передай этот sessionId в POST /api/datasets/ingest, чтобы начать обработку. См. документацию по данным.

Получить подписанный URL для загрузки#

POST /api/upload/signed-url

Запроси подписанный URL для прямой загрузки файла в облачное хранилище. Подписанный URL позволяет обойти API-сервер при передаче больших файлов.

Тело запроса:

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

Ответ:

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

Завершить загрузку#

POST /api/upload/complete

Уведомь платформу о завершении загрузки файла. Для моделей это прикрепляет загруженные веса. Для архивов датасетов это проверяет и регистрирует сеанс загрузки; вызови POST /api/datasets/ingest после этого, чтобы начать обработку датасета.

Тело запроса:

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

API интеграций#

Импортируй датасеты из сторонних сервисов. См. документацию по интеграциям.

Предпросмотр импорта из Roboflow#

POST /api/integrations/roboflow/preview

Преобразует API-ключ Roboflow в план массового импорта: информация о рабочей области, проекты, которые будут импортированы впервые, количество уже импортированных версий (пропущены) и неподдерживаемые типы проектов. API-ключ Roboflow передается в теле запроса и не сохраняется.

Импорт из Roboflow#

POST /api/integrations/roboflow/import

Поставить в очередь задания на прием набора данных для импорта выбранных проектов Roboflow в твою рабочую область. Требуется свободное место в хранилище, и каждый набор данных должен соответствовать лимиту размера на импорт твоего плана.

API Keys API#

Управляй своими ключами API для программного доступа. См. документацию по ключам API.

Список API keys#

GET /api/api-keys

Клиенты, прошедшие аутентификацию по ключу API, получают метаданные ключа, но никогда не получают расшифрованные значения существующих ключей. Вновь созданный ключ возвращается один раз методом POST /api/api-keys.

Передай необязательный параметр запроса owner, чтобы управлять ключами для рабочего пространства, к которому у тебя есть доступ редактора.

Создать API key#

POST /api/api-keys

Тело запроса:

{
    "name": "training-server"
}

Удалить API key#

DELETE /api/api-keys

Параметры запроса:

Пример:

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

Teams & Members API#

Создавай командные рабочие пространства, приглашай участников и управляй ролями для совместной работы. См. документацию по командам.

Список команд#

GET /api/teams

Создать команду#

POST /api/teams/create

Тело запроса:

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

Список участников#

GET /api/members

Возвращает участников текущего рабочего пространства.

Пригласить участника#

POST /api/members

Тело запроса:

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

Обновить роль участника#

PATCH /api/members/{userId}

Удалить участника#

DELETE /api/members/{userId}

Передача прав владения#

POST /api/members/transfer-ownership

Explore API#

Ищи и просматривай публичные датасеты и проекты, которыми поделилось сообщество. См. документацию по обзору.

Поиск общедоступного контента#

GET /api/explore/search

Параметры запроса:

Данные боковой панели#

GET /api/explore/sidebar

Возвращает отобранный контент для боковой панели Explore.

User & Settings APIs#

Управляй своим профилем, ключами API, использованием хранилища и командными рабочими пространствами. См. документацию по настройкам.

Сводка учетной записи#

GET /api/account/summary

Возвращает план аутентифицированной учетной записи, кредитный баланс, количество ресурсов и рабочие области команды.

Получить пользователя по имени пользователя#

GET /api/users

Параметры запроса:

Подписаться или отписаться от пользователя#

PATCH /api/users

Тело запроса:

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

Проверить доступность имени пользователя#

GET /api/username/check

Параметры запроса:

Настройки#

GET /api/settings
POST /api/settings

Получи или обнови настройки профиля пользователя (отображаемое имя, биография, ссылки на соцсети и т.д.).

Иконка рабочей области#

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

Загрузи иконку профиля/рабочего пространства WebP размером до 5 МБ в качестве поля формы multipart image или удали ее. Передай необязательный параметр owner для командного рабочего пространства.

Интеграция с Python#

Для упрощения интеграции используй пакет Python от Ultralytics, который автоматически обрабатывает аутентификацию, загрузку и потоковую передачу метрик в реальном времени.

Установка и настройка#

pip install "ultralytics>=8.4.104"

Проверь установку:

yolo check

Аутентификация#

yolo login YOUR_API_KEY

Использование датасетов платформы#

Ссылка на датасеты с помощью 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,
)

Формат URI:

Отправка на платформу#

Отправляй результаты в проект на платформе:

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

Что синхронизируется:

• Метрики обучения (в реальном времени)
• Финальные веса модели
• Графики валидации
• Вывод консоли
• Системные метрики

Примеры API#

Загрузи модель с платформы:

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

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

Запусти инференс:

results = model("image.jpg")

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

Экспорт модели:

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

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

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

Валидация:

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

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

FAQ#

Как мне использовать пагинацию для больших результатов?#

Большинство эндпоинтов используют параметр limit для управления количеством результатов, возвращаемых за один запрос:

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

Эндпоинты Activity и Trash также поддерживают параметр page для постраничной пагинации:

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

Эндпоинт Explore Search использует offset вместо page с фиксированным размером страницы 20:

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

Могу ли я использовать API без SDK?#

Описанные выше общедоступные операции REST API доступны без Python SDK. SDK представляет собой удобную обертку, которая добавляет такие функции, как потоковая передача метрик в реальном времени и автоматическая выгрузка моделей. Ты можешь интерактивно изучить машиночитаемый контракт по адресу platform.ultralytics.com/api/docs; потоки учетных записей, доступные только в рамках сеанса браузера, остаются в пользовательском интерфейсе Platform.

Существуют ли клиентские библиотеки API?#

Используй пакет Python для Ultralytics или выполняй прямые HTTP-запросы из любого языка.

Как мне обрабатывать лимиты запросов?#

Используй заголовок Retry-After из ответа 429, чтобы выждать нужное время:

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

Как найти ID моей модели или датасета?#

Идентификаторы ресурсов возвращаются в ответах API при создании, получении списка и получении ресурса. URL-адреса страниц платформы используют понятные человеку ярлыки (slugs), а не идентификаторы базы данных:

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

Используй эндпоинты списка, чтобы найти соответствующий _id для модели, датасета, проекта, развертывания или другого ресурса.