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

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

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

Обзор API#

API организован вокруг основных ресурсов Platform:

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

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

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

Для большинства конечных точек требуется API-ключ. Конечные точки, предоставляющие доступ к публичному контенту — например, чтение публичного датасета, проекта или модели, просмотр списка изображений публичного датасета, запуск инференса на публичной модели или поиск в Explore, — также принимают анонимные запросы и просто возвращают больше данных, если передан ключ.

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

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

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

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

Передавай API-ключ в виде токена Bearer:

Authorization: Bearer YOUR_API_KEY

Пример#

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

Базовый URL#

Для всех конечных точек API используется:

https://platform.ultralytics.com/api

Пути к ресурсам#

Большинство ресурсов доступны по тем же понятным человеку именам, что и в URL Platform, а не по идентификаторам базы данных:

• {owner} — это имя пользователя или идентификатор командного рабочего пространства: от 4 до 32 символов, строчные буквы и цифры, сегменты разделяются одиночными дефисами.
• {dataset}, {project}, {model} и {deployment} соответствуют тому же формату: строчные буквы и дефисы, не более 128 символов.
• {imageId}, {exportId} и {agentId} — это 24-символьные шестнадцатеричные идентификаторы, возвращаемые API.
• При переименовании ресурса через PATCH одновременно меняются отображаемое имя name и имя в URL; в ответе возвращается текущее имя в URL, чтобы ты мог продолжать использовать его.

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

API ограничивает частоту запросов для каждого API-ключа по скользящему окну. Каждый маршрут относится к одной категории, и для каждой категории ведется отдельный счетчик, поэтому 20 запросов predict не расходуют лимит по умолчанию.

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

При превышении лимита API возвращает 429 в заголовках и теле JSON:

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

{
    "error": "Rate limit exceeded, wait 12s",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

Выделенные конечные точки (без ограничений)#

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

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

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

Ответы представляют собой JSON-объекты с полями, зависящими от ресурса. Общей оболочки нет: конечные точки для получения списков возвращают именованную коллекцию, обычно вместе с количеством элементов, а операции изменения — измененные идентификаторы.

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

Списки ресурсов, ответы на создание и клонирование, а также некоторые ответы на запросы, например о развертываниях, хранилище и корзине, также содержат region (us, eu или ap) — регион хранения для этой рабочей области.

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

Каждый ответ с ошибкой — это JSON-объект с сообщением error:

{
    "error": "Dataset not found"
}

Пагинация#

Способ пагинации зависит от коллекции:

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

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

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

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

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

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

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

Ответ:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

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

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

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

Возвращает полный объект набора данных под ключом dataset, включая classNames, splits, versions, source и пользовательский объект metadata. Пока обрабатывается импорт 10 000 или более изображений, редакторы также получают processingProgress с stage, percent и, если они известны, processed, total и objects (просканированные облачные объекты).

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

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

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

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

Если в рабочей области уже существует слаг dataset, в том числе в корзине, возвращается 409.

Ответ (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

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

PATCH /api/datasets/{owner}/{dataset}

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

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

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

Допустимые поля: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter, starred, blurFaces, kptSkeletonId (назначить шаблон скелета позы набору данных с позами) и initializeClassNames (обновление возвращает 409, если только в наборе данных еще нет классов или аннотаций). Чтобы очистить пользовательские метаданные, отправь пустой объект metadata ({}). Ключи метаданных могут содержать не более 128 символов, а сериализованный объект — не более 500 000 символов.

Ответ:

{
    "success": true,
    "dataset": "warehouse-safety"
}

При переименовании меняется имя в URL, поэтому для последующих запросов используй возвращенное значение dataset.

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

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

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

Перемещает набор данных в корзину, откуда его можно восстановить в течение 30 дней.

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

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

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

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

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

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

Ответ (201): id, owner, dataset, name, imageCount, classCount и region. Для наборов данных, подключенных к источнику хранилища, возвращается 409, поскольку файлы не копируются.

Скачать экспорт набора данных#

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

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

Возвращает подписанный URL для скачивания NDJSON. Не указывай v, чтобы экспортировать текущее состояние набора данных; если с момента создания экспорта ничего не изменилось, будет использован кэшированный экспорт.

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

Ответ:

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

При запросе конкретной версии возвращаются downloadUrl и version вместо cached.

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

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

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

Создает неизменяемую версию набора данных с номером. Требуется доступ редактора. Установи download в false, чтобы сохранить версию без подготовки загрузки NDJSON; в таком случае downloadUrl не возвращается. SDK принимает download из ultralytics-platform>=0.1.73.

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

{
    "description": "Added 500 training images",
    "download": true
}

Ответ:

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

Если набор данных совпадает с существующей версией, reused принимает значение true — например, сразу после восстановления. Вместо этого возвращается та версия; если ты передал описание, оно обновляется.

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

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

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

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

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

Ответ: {"ok": true}

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

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

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

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

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

{
    "version": 2
}

Ответ: {"version": 2, "imageCount": 1000}

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

GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}

Python SDK: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)

Ответ (сокращенный):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summary появляется только на первой странице и содержит точные итоговые данные, а также header, в котором перечислены добавленные, удаленные или переименованные классы и другие отличающиеся поля набора данных. Для каждого элемента change имеет значение added, removed, modified (с измененным fields) или moved (изменен сплит), а labelsRemoved содержит метки удаленных изображений. Если присутствует nextCursor, передай его как cursor для получения следующей страницы. При использовании hash ответ содержит versions: изображение в том виде, в каком оно хранится в каждой версии, его метки и подписанный imageUrl. Порядок не имеет значения: если поменять местами base и head, удаленное изображение будет указано как добавленное. Для сравнений действует стандартный лимит частоты запросов; запросы без hash также ограничены 10 запросами в минуту для каждого пользователя и набора данных независимо от того, какой API-ключ используется.

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

GET /api/datasets/{owner}/{dataset}/class-stats

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

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

Ответ (сокращённый):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "forklift"],
    "cached": true,
    "sampleSize": null
}

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

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

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

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

Удалить классы (их аннотации будут удалены, а идентификаторы оставшихся классов сдвинутся вниз):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

Обе операции возвращают success, обновлённые classNames и classColors, а также сводку изменений (mergedClassIds и targetClassId либо deletedClassIds и deletedAnnotations).

Перераспределить разбиения#

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

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

Случайным образом распределяет изображения по разбиениям. Сумма трёх процентов должна составлять 100.

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

Ответ: success, получившееся количество элементов в splits и modified (число перемещённых изображений).

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

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)

GET возвращает сводку анализа (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST ставит анализ эмбеддингов в очередь и возвращает 202 с jobId. DELETE отменяет активную задачу и возвращает ID отменённой задачи или null.

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

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

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

Возвращает двумерное представление UMAP по завершённому анализу с постраничной выдачей через offset и limit (по умолчанию и максимум — 50 000). Для каждой записи указаны id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled и missing. cluster — это визуальный остров точки, ранжированный по размеру (0 = самый большой, -1 = рассеянный), либо null для представлений, проанализированных до появления кластеризации.

Список моделей, обученных на наборе данных#

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

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

Ответ:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

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

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

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

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

Ответ:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

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

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

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

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

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

Копирование или перемещение изображений#

POST /api/datasets/{owner}/{dataset}/images/adopt

Python SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

Копирует в этот набор данных до 1 000 изображений из других наборов данных, как это делает функция приложения копирования и вставки, и возвращает количество adopted.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

Указание release или classMapping сохраняет метки и разбиение на части для наборов данных, которые ты можешь редактировать: release: false копирует изображения, а release: true перемещает их из исходного набора данных. Если не указать ни одно из этих полей, импортируются изображения train без меток; то же происходит при копировании из источника только для чтения. При перемещении из источника только для чтения возвращается 403. Существующие изображения пропускаются; при сохранении меток и разбиения на части дубликаты проверяются в целевой части. Классы сопоставляются по названию без учета регистра для названий длиной более двух символов; 422 возвращает исходные классы, для которых нет совпадения в unmatchedClasses, а classMapping сопоставляет каждый класс с индексом класса, новым названием класса или null, чтобы удалить его метки. 409 означает, что целевой набор данных подключен либо исходный или целевой набор данных занят. При сохранении меток и разбиения на части несовместимость задач, каналов изображения, настроек позы или шкал глубины также приводит к 409, даже для изображений без меток.

Импорт данных в набор данных#

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

Python SDK: client.datasets.ingest(owner, dataset, body=...)

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

Сеансы загрузки привязаны к набору данных через assetId, переданный в POST /api/upload/signed-url; импорт отклоняет сеанс, связанный с другим набором данных.

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

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

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

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

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

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

Тело запроса (добавление метаданных для каждого изображения):

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

Ключи метаданных должны совпадать с нормализованным путём внутри архива, включая папки. При импорте NDJSON каждая запись может содержать собственный объект metadata, который имеет приоритет над соответствующей записью imageMetadata. Длина путей в архиве ограничена 1 024 символами, ключей метаданных верхнего уровня — 128 символами, а каждого объекта метаданных и всей карты imageMetadata — 500 000 сериализованных символов.

Ответ (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D["POST /api/upload/complete (optional)"]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/ingest"]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
image_path = Path("airbus-wing.jpg")

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

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

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

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

API изображений#

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

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

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

Возвращает объект metadata (пользовательские данные), properties (имя файла, хеш, размеры, разбиение, количество объектов, временные метки), labels и classNames набора данных.

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

PATCH /api/images/{imageId}

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

Заменяет либо аннотации, либо пользовательские метаданные — отправь одну из двух структур, но не обе.

Тело запроса (аннотации):

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

Тело запроса (метаданные):

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

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

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

Безвозвратно удаляет одно изображение и его аннотации.

Автоматически аннотировать изображение#

POST /api/images/{imageId}/predict

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

Запускает модель на изображении и возвращает предсказанные аннотации. Они не сохраняются — запиши результаты обратно с помощью PATCH /api/images/{imageId}, когда они тебя устроят.

Ответ: success, predictions (объекты аннотаций), confidences (оценки, выровненные по индексам; для моделей с запросом классов список пуст), modelUsed, inferenceTime; для моделей с запросом классов — partial (true, если генеративная модель вернула из усечённого вывода только полные рамки); для моделей платных провайдеров — необязательный cost (предполагаемая стоимость услуг провайдера в долларах США, списываемая с ключа провайдера; поле отсутствует, если оценка недоступна). Если классы модели YOLO не соответствуют набору данных, возвращается 422; то же происходит с моделью, использующей запрос классов, если набор данных предназначен не для обнаружения или содержит не от 1 до 200 классов, а также с моделью платного провайдера, если ключ провайдера не сохранён в Settings > API Keys рабочей области набора данных (code: missing_provider_api_key). Ошибка провайдера содержит сообщение провайдера: 422, если провайдер отвечает 400, 401, 403 или 404 (отклонённый ключ, модель или запрос); 429 — при достижении лимита запросов, а 503 — при любой другой ошибке провайдера. Для наборов данных глубины возвращается 400, а для наборов данных в подключённом хранилище или с более чем 3 каналами изображения — 409.

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

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

Возвращает до 24 визуально похожих images из общедоступных наборов данных, а также из твоих личных и командных наборов данных. Для каждого указаны score (от 0 до 1), подписанный thumbnailUrl и исходный dataset (owner, dataset, license). Изображения, уже присутствующие в исходном наборе данных, и копии изображения-запроса исключаются. Требуется API-ключ с правом просмотра изображения; если для изображения ещё не создан эмбеддинг, сначала он создаётся, а 503 означает, что подготовка не удалась и запрос нужно повторить.

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

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)

Сохраняет версию набора данных, затем ставит в очередь запуск, который размечает моделью неразмеченные изображения набора данных, и возвращает 202. Тело запроса принимает те же поля modelId, confidence, iou и classMapping, что и endpoint для одного изображения, а также includeAnnotated (по умолчанию false), чтобы аннотировать также изображения, у которых уже есть метки. Модель с запросом классов обнаруживает классы набора данных без оценок уверенности, а для модели платного провайдера требуется ключ провайдера, сохранённый в рабочей области набора данных в разделе Settings > API Keys (422, code: missing_provider_api_key, до допуска запуска). Существующие метки никогда не изменяются, а оплата за запуск взимается за изображения, которые он фактически обрабатывает. 402 означает, что средств недостаточно для покрытия оценочной стоимости; 409 — что набор данных не готов, в нём не осталось изображений для аннотирования или уже выполняется запуск; 422 — что в наборе данных нет классов либо что модель с запросом классов используется с набором данных не для обнаружения или с числом классов вне диапазона 1–200. Перед вызовом этого endpoint создай классы через endpoint классов: именно это делает шаг «Сопоставить классы» в приложении перед запуском.

GET по тому же пути (client.datasets.batch(owner, dataset)) возвращает выполняющийся запуск и его прогресс либо последний завершённый запуск до его закрытия; в его results включён partialImages, если при запуске генеративной модели из усечённого вывода оставлены только полные рамки. DELETE (client.datasets.delete_batch(owner, dataset)) отменяет выполняющийся запуск либо завершает расчёты и закрывает сводку завершённого запуска.

Тот же endpoint размывает лица с помощью "operation": "blur", confidence (по умолчанию 0.25) и boxScale (0.5–1.5, по умолчанию 1); imageId ограничивает запуск одним изображением. Версия не создаётся, а метки не изменяются. Отправь "preview": true, чтобы обработать до шести изображений без внесения изменений, а затем передай возвращённый jobId как previewJobId с теми же настройками, чтобы применить результат; повторно использовать применённый предварительный просмотр нельзя — возвращается 409. Пока предварительный просмотр ожидает применения, передай его ID в DELETE как previewJobId, чтобы удалить его.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

Массовое перемещение изображений#

PATCH /api/images/bulk

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

Перемещает до 1 000 изображений из одного набора данных в другое разбиение.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

При конфликте имён файлов или содержимого возвращается 409, пока ты не выберешь единый для всей группы параметр conflictPolicy: skip, keep_both или replace. В ответе указаны modifiedCount, skippedCount и targetSplit.

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

DELETE /api/images/bulk

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

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

Удаляет до 1 000 изображений из одного набора данных и возвращает deletedCount и deletedImageIds.

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

POST /api/images/urls

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

Возвращает временные подписанные URL для не более чем 100 ID изображений из одного набора данных.

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

Ответ: urls, thumbnails и depths (предварительные просмотры целевых данных глубины для парных изображений глубины); все значения сгруппированы по ID изображения.

API проектов#

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

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

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

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

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

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

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

Возвращает объект project, массив models со сводками по каждой модели (статус, метрики, эпохи, веса, аргументы обучения) и isOwner. Передай search (максимум 200 символов), чтобы отфильтровать models по имени модели или метаданным.

Создание проекта#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

Ответ (201): id, owner, project, region.

Если в рабочей области уже существует слаг project, в том числе в корзине, возвращается 409.

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

PATCH /api/projects/{owner}/{project}

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

Допустимые поля: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences и starred.

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

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

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

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

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

Перемещает проект и его модели в корзину, возвращая cascadedModels, и безвозвратно удаляет их развертывания. Восстановление проекта не восстанавливает развертывания. 502 означает, что очистка развертываний не завершилась; модели останутся в корзине, пока она не завершится.

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

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

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

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

API моделей#

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

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

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

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

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

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

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

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

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

Ответ по умолчанию содержит объект model — статус, задачу, метрики, trainArgs, trainResults, classNames, computeCost, metadata и другие поля, — а также isOwner.

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

POST /api/models

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

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

Ответ (201): id, owner, project, model, region.

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

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

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

Допустимые поля включают name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError и starred. Если передать только projectId, модель переместится в другой проект того же владельца; в ответе будут указаны slug модели в целевом проекте, renamed: true, если это имя уже занято в целевом проекте, и 409, пока модель продолжает обучаться.

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

Пользовательское поле metadata отделено от полей, которыми управляет обучение, например trainArgs, environment и trainResults; для него действуют те же ограничения размера, что и для метаданных набора данных.

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

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

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

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

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

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

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

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

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

Найти изображения, похожие на изображения с худшими результатами валидации#

GET /api/models/{owner}/{project}/{model}/similar-images

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

Возвращает до 100 объектов images в том же формате, что и поиск похожих изображений. Это изображения, похожие на те, на которых данный запуск обучения показал худшие результаты, за исключением изображений, уже имеющихся в обучающем наборе данных. Передай hashes (список до 100 элементов через запятую), чтобы выполнять поиск по подмножеству этих изображений с худшими результатами. Требуется API-ключ с доступом к рабочему пространству модели. Список будет пустым, если для запуска не были сохранены результаты по отдельным изображениям; 404 также означает, что для изображений с худшими результатами еще не созданы эмбеддинги: сначала создай эмбеддинги набора данных для обучающего набора.

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

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

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

Копирует доступную модель в существующий проект.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

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

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

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

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

Составная форма:

Укажи либо file, либо source. Для моделей глубины также можно передать bits (8, 12 или 16), чтобы выбрать квантование PNG-карты глубины. Если запрос превышает ограничения сервиса на входные данные, возвращается 413.

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

Ответ:

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

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "forklift"],
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

Проверить ход обучения#

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

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

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

Отмена обучения#

DELETE /api/models/{owner}/{project}/{model}/training

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

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

API обучения#

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

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

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

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

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

Возвращает текущий статус наличия ресурсов с привязкой к ID GPU. Доступно всем без аутентификации; передай managed=true, чтобы включить мощности управляемого обучения — для этого потребуется API-ключ.

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

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

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

Ответ:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

Если на балансе недостаточно средств, обучение возвращает 402; если для запрошенного GPU нет доступных мощностей, возвращается 503.

API экспорта#

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

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

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

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

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

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

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

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

Для каждого формата действуют только параметры из столбца Аргументы таблицы экспорта ниже: если для формата, который не поддерживает параметр, указать отличное от значения по умолчанию значение batch, dynamic, opset, simplify, workspace или optimize, вернется 400. Экспорты imx доступны только в INT8 для моделей обнаружения, сегментации, классификации и поз. Для моделей YOLO26 и моделей YOLOv8 или YOLO11 размером не nano вернется 400.

Ответ (201): id, format, status (queued или running), region и gpuType для экспортов TensorRT. Если эквивалентный экспорт уже выполняется, возвращается 409.

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

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

nms=None по умолчанию возвращает исходные выходные данные для внешней NMS. Укажи nms=False, чтобы выбрать доступную голову без NMS; неподдерживаемые форматы используют собственный путь вывода. Элементы nms выше обозначают форматы, в которые можно встроить NMS с помощью nms=True.

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

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

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

Возвращает объект export с полями status, format, args, gpuType (только для TensorRT), временными метками и, после завершения, объектом file, содержащим size, downloadUrl и downloadFilename.

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

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

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

Отменяет выполняющийся экспорт или удаляет завершенный экспорт и его файл. В ответе указывается, какое действие выполнено:

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

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

Развертывай модели на выделенных конечных точках инференса с проверками работоспособности и мониторингом. Подробнее см. в документации по конечным точкам.

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

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

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

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

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

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

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

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

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

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

Ответ (201): id, deployment, status (creating), message и region.

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

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

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

Возвращает объект deployment с status, statusMessage, region, serviceUrl, resources и пользовательским metadata, а также camera и cameraApplying для владельца.

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

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

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

Отправь одно из следующих тел запроса:

{ "name": "Edge 1 (primary)" }

При переименовании значение deployment в URL заменяется на слаг нового названия, возвращаемый как deployment; старый путь возвращает 404, а serviceUrl не меняется. Пустой объект metadata очищает пользовательские метаданные. При замене выполняется развертывание новой версии с сохранением идентификатора развертывания, региона и URL конечной точки; если развертывание не удается, текущая версия продолжает работать. Модель для замены должна быть завершенной и иметь веса, к которым у твоего ключа есть доступ. Действие с камерой сохраняет камеру RTSP или RTSPS, для которой готовая конечная точка с пользовательскими ресурсами непрерывно выполняет инференс (см. раздел Камера в фоновом режиме); "url": null удаляет ее. Камера также удаляется при возврате к размеру по умолчанию; сохранение камеры на конечной точке стандартного размера возвращает 403. При изменении камеры возвращается 202 с status ready на время применения изменений: опрашивай развертывание, пока cameraApplying не перестанет быть true, а затем проверь camera; если изменить камеру не удастся, останется прежняя камера и будет установлено значение statusMessage. Завершенные операции возвращают 200 с status ready или stopped; если другие операции все еще выполняются, возвращается 202 с deploying или stopping.

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

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

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

Безвозвратно удаляет конечную точку инференса.

Проверка качества#

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

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

Проверяет доступность конечной точки и прогревает ее, возвращая healthy, latencyMs и код status от вышестоящего сервиса.

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

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

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

Передает изображение или видео через выделенную конечную точку. Контракты запроса и ответа совпадают с контрактами инференса модели. Потоки с камер не проксируются; отправляй их на URL конечной точки, как описано в разделе Инференс с камеры в реальном времени.

Составная форма:

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

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

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

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

Полный ответ содержит summary (общее число запросов, доля ошибок, средняя задержка, а также задержки p50/p95/p99) и timeSeries (запросы, ошибки, задержка, CPU, память, количество экземпляров). Ответ со спарклайнами возвращает requests24h (почасовое число запросов; часы без запросов не включаются), totalRequests, errorRate и avgLatencyMs (среднее значение почасовых задержек P95). При наличии view=overview в summary содержатся totalRequests, errorRate и p95LatencyMs, а в timeSeries — requests, errors и latencyP95.

Получить журналы#

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

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

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

API агентов#

Сохраняй рабочие процессы агентов и управляй ими. API хранит определения агентов; запуски начинаются на холсте «Агенты», где https://platform.ultralytics.com/agents?workflow={id} открывает сохраненного агента. Для методов Python SDK требуется ultralytics-platform>=0.1.74.

Для каждой операции можно указать необязательный параметр запроса owner с именем пользователя рабочего пространства, в котором ты состоишь (по умолчанию используется твое рабочее пространство). Для просмотра нужен доступ уровня Viewer; для сохранения и удаления — уровня Editor.

Получить список агентов#

GET /api/workflows

Python SDK: client.agents.list()

В ответе перечисляется до 100 агентов в workflows, сначала недавно обновленные. Для каждого агента указаны id, username, name, version, createdAt и updatedAt. Если запросить id, также возвращается graph агента.

Сохранить агента#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

Отправь version: 0, чтобы создать агента. Чтобы обновить агента, отправь его id и version, полученный при последнем запросе списка или сохранении; устаревший version возвращает 409, поэтому снова запроси агента и повтори попытку. Если связи в графе образуют цикл или у блока больше одного входа, возвращается 400.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

В ответе возвращаются агент id, его новый version и errors: блоки, которые холст отметил бы, например блок Dataset, для которого не выбран набор данных. Агент сохраняется в любом случае. Список всех типов блоков и их конфигураций см. в openapi.json.

Удалить агента#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

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

API корзины#

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

Получить список элементов в корзине#

GET /api/trash

Python SDK: client.lifecycle.trash()

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

Ответ содержит items (для каждого элемента указано daysRemaining), total, page, limit, totalPages и summary с общим количеством элементов по типам. Если указать id, вместо этого возвращается resources: модели, которых коснется действие, и развертывания, которые будут безвозвратно удалены.

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

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

При восстановлении проекта также восстанавливаются модели, удаленные вместе с ним; они перечислены в restoredModels.

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

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

Удалить один элемент:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

Или очистить всю корзину:

{
    "all": true
}

В ответе указывается deletedCount, а также cascadedModels и survivingDeployments, если применимо.

API загрузки#

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

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

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

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

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

Ответ:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z",
    "headers": { "x-goog-if-generation-match": "0" }
}

Загрузи файл запросом PUT на uploadUrl, используя то же значение Content-Type, которое ты указал, и все заголовки из headers. URL для загрузки наборов данных действуют 12 часов и позволяют создать файл только один раз: повторный PUT на тот же URL возвращает 412, а PUT без полученных заголовков возвращает 400.

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

POST /api/upload/complete

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

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

Ответ: success и объект file с size и contentType. Для моделей это прикрепляет веса; для архивов наборов данных затем вызови импорт, чтобы начать обработку.

Если передан md5, его значение сверяется с сохраненным объектом. При несовпадении возвращается 400; если сессия еще не завершена, загруженный файл также удаляется, а сессия остается незавершенной. Запроси новый подписанный URL и загрузи файл повторно. Завершенную сессию набора данных можно завершить повторно, пока архив существует, но при конкурирующих запросах на завершение с разными дайджестами возвращается 409; сессии моделей удаляются при завершении. checksum сохраняется как метаданные файла модели и не проверяется.

API интеграций с хранилищами#

Подключай учетные записи Google Cloud Storage, Amazon S3 или Azure Blob Storage только для чтения и просматривай их как источники наборов данных. См. документацию по интеграциям.

Для обнаружения и подключения хранилищ нужен доступ администратора рабочего пространства и тарифный план Pro или Enterprise (иначе 403); для просмотра интеграций и объектов нужен доступ уровня Editor.

Получить список интеграций#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

Возвращает integrations; для каждой интеграции указаны id, provider, credentialIdentity, targets и createdAt. Учетные данные никогда не возвращаются.

Обнаружить расположения#

POST /api/integrations/buckets/discover

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

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

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

Ответ: {"targets": ["my-bucket", "another-bucket"]}

Подключить хранилище#

POST /api/integrations/buckets

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

Формат учетных данных такой же, как для обнаружения, но дополнительно требуется массив targets с 1–50 именами бакетов или контейнеров. Возвращает 201 с сохраненной интеграцией. Временные учетные данные S3 (ключи доступа ASIA) не поддерживаются.

Просмотреть объекты#

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

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

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

Возвращает entries (каждый kind имеет значение folder или file) и необязательный cursor для следующей страницы.

Отключить хранилище#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

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

API импорта наборов данных#

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

Предварительный просмотр импорта из Roboflow#

POST /api/integrations/roboflow/preview

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

По ключу API Roboflow формирует план импорта: сведения о рабочем пространстве, newDatasets, которые будут импортированы, количество уже импортированных (skippedCount), проектов без версии, неподдерживаемых и неразрешенных проектов, bytesTotal и доступный остаток хранилища storage. Ключ API Roboflow считывается из тела запроса и не сохраняется.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Импорт из Roboflow#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

Ставит в очередь задачи импорта для не более чем 500 выбранных версий проектов Roboflow, используя элементы, возвращенные при предварительном просмотре.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

Ответ (201): массивы imported, failed и skipped. Для импорта нужен свободный объем хранилища, а размер каждого набора данных не должен превышать лимит размера на импорт для твоего тарифного плана.

API учетной записи#

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

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

GET /api/account/summary

Python SDK: client.account.summary()

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

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

Получить список ключей API#

GET /api/api-keys

Python SDK: client.account.api_keys()

Возвращает keys с полями keyId, name, keyPrefix и createdAt для рабочего пространства ключа. Запросы с аутентификацией по ключу API получают только метаданные; полные значения ключей видны владельцу рабочего пространства в интерфейсе Platform в разделе Настройки > Ключи API, где также можно создавать и отзывать ключи.

Проверить использование хранилища#

GET /api/storage

Python SDK: client.account.storage()

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

Ответ:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

usage сообщает количество projects, datasets, models, images, annotations и deployments, а также размер в байтах для storage. Значение limit равное -1 означает отсутствие ограничений, а percent — это процент от лимита, выраженный целым числом.

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

GET /api/users

Python SDK: client.account.profile(username=...)

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

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

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

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

Ответ: followed и обновленный followerCount.

API биллинга#

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

Просмотр тарифного плана и использования#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

Возвращает plan (идентификатор, статус, расчетный период, окончание периода), metrics (лимит хранилища и его использование), trainingCredit, features, creditsCents и количество мест.

Просмотр транзакций#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

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

Каждая транзакция включает id, type (например, purchase, training, monthly_grant или refund), amountCents, balanceAfter, createdAt, необязательный receiptUrl и контекст модели для платы за обучение. Внутренние сведения о биллинге никогда не возвращаются.

API раздела Explore#

Ищи общедоступные проекты и наборы данных, которыми делится сообщество, или изображения по их содержимому. См. документацию по разделу «Обзор».

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

GET /api/explore/search

Python SDK: client.explore.search()

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

Ответ: projects, datasets и hasMore. Вместо этого type=images возвращает совпадения в images, сначала наиболее подходящее, каждое с исходным dataset и оценкой сходства от 0 до 1 score; для этого требуется q. Выполняется поиск по общедоступным наборам данных, а также по твоим собственным и командным наборам данных, если ты передашь API-ключ.

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

Python SDK#

ultralytics-platform — типизированный клиент Python, сгенерированный на основе контракта OpenAPI, с отдельным методом для каждой конечной точки (client.datasets.list, client.models.predict, client.exports.create, ...). Каждый метод принимает параметры пути позиционно, другие входные данные — как именованные аргументы, а также необязательные timeout и extra_headers для каждого запроса.

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

from ultralytics_platform import Platform

with Platform() as client:  # читает ULTRALYTICS_API_KEY или ключ, сохранённый командой yolo login
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform предоставляет то же дерево ресурсов для кода async/await, неуспешные ответы вызывают APIError с status_code, body и разобранным json, а ошибки подключения вызывают APIConnectionError. Полный README см. в репозитории SDK.

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

Для сценариев обучения и инференса используй пакет Ultralytics для Python: он автоматически обрабатывает аутентификацию, загрузку файлов и передачу метрик в реальном времени. В Python 3.11+ pip install ultralytics также устанавливает SDK ultralytics-platform. Когда model.train(project=...) указывает на Platform, колбэки обучения передают события через client.training.metrics() SDK и запрашивают URL для загрузки контрольных точек через client.models.upload_checkpoint() — операции POST /api/webhooks/training/metrics и POST /api/webhooks/models/upload в документе OpenAPI, поэтому тебе не нужно вызывать их самостоятельно.

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

Для интеграции с Platform требуются Python>=3.11 и ultralytics>=8.4.120:

pip install "ultralytics>=8.4.120"

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

yolo check

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

yolo login YOUR_API_KEY

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

Указывай датасеты с помощью URI ul://:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Обучение на датасете Platform
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

Формат URI:

Отправка в Platform#

Отправь результаты в проект Platform:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Результаты автоматически синхронизируются с Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

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

• Метрики обучения (в реальном времени)
• Итоговые веса модели
• Графики валидации
• Вывод консоли
• Системные метрики
• Аргументы обучения и среда хоста (имя хоста, ОС, Python, оборудование, коммит git, командная строка)

Примеры API#

Загрузка модели из Platform:

# Твоя модель
model = YOLO("ul://username/project/model-name")

# Официальная модель
model = YOLO("ul://ultralytics/yolo26/yolo26n")

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

results = model("image.jpg")

# Доступ к результатам
for r in results:
    boxes = r.boxes  # Боксы детекций
    masks = r.masks  # Маски сегментации
    keypoints = r.keypoints  # Ключевые точки позы
    probs = r.probs  # Вероятности классов

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

# Экспортируй в ONNX
model.export(format="onnx", imgsz=640, quantize=16)

# Экспортируй в TensorRT
model.export(format="engine", imgsz=640, quantize=16)

# Экспорт в CoreML
model.export(format="coreml", imgsz=640)  # используй imgsz=224 для классификации

Валидация:

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

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

Часто задаваемые вопросы#