Справочник 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. Нажми Create Key
3. Скопируй созданный ключ

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

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

Передавай свой ключ 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} — это 24-символьные шестнадцатеричные идентификаторы, возвращаемые API.
• Переименование ресурса через PATCH одновременно изменяет отображаемое имя name и имя в URL, а ответ возвращает текущее имя в URL, чтобы ты мог продолжать переходить по нему.

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

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

Маршруты Platform, доступные только из браузера (такие как оплата счетов и управление командой), имеют собственные лимиты, которые не распространяются на трафик по ключу API.

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

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

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

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

Выделенные эндпоинты не подпадают под ограничения лимита запросов API-ключа Platform, когда ты обращаешься напрямую к собственному 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.

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

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

Ответ (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. Отправь пустой объект 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)

Создает неизменяемый нумерованный снимок датасета и сохраняет его NDJSON-экспорт. Требует прав редактора.

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

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

Ответ:

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

Удалить классы (их аннотации удаляются, а оставшиеся ID классов смещаются вниз):

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)

Возвращает 2D-раскладку UMAP по результатам завершенного анализа, с пагинацией по offset и limit (по умолчанию и макс. 50 000). Каждый элемент содержит id, umapX, umapY, split, classIds, width, height, bytes, labelCount и missing.

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

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.jpg",
            "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=...)

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

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

Загрузка данных в датасет#

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. Пути в архиве ограничены 1024 символами, ключи метаданных верхнего уровня — 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]:::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()

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/{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=...)

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

Ответ: success, predictions (объекты аннотаций), modelUsed и inferenceTime. Модель, чьи классы не соответствуют датасету, возвращает 422.

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

PATCH /api/images/bulk

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

Перемещает до 1000 изображений из одного датасета в другую выборку.

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

Удаляет до 1000 изображений из одного датасета и возвращает deletedCount и deletedImageIds.

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

POST /api/images/urls

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

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

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

Ответ: urls и thumbnails, оба с ключами по 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.

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

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.

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

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.

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

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.

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

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

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-ключ с доступом к родительскому проекту.

Multipart Form:

Укажи либо 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,
        "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, если твой баланс кредитов слишком мал, и 503, если для запрошенного GPU нет свободных мощностей.

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

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

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

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

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

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

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

Возвращает объект export с status, format, args, gpuType, метками времени и — после завершения — объектом 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.

Запуск, остановка или замена развертывания#

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

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

Единственное поле action задает операцию:

{ "action": "start" }

Замена развертывает новую ревизию, сохраняя ID развертывания, регион и URL эндпоинта; существующая ревизия остается активной в случае сбоя развертывания. Заменяющая модель должна быть завершенной моделью с весами, к которым у твоего ключа есть доступ. Завершенные операции возвращают 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=...)

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

Multipart Form:

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

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

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

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

Полный ответ содержит summary (всего запросов, частота ошибок, средняя задержка и p50/p95/p99) и timeSeries (запросы, ошибки, задержка, CPU, память, количество экземпляров). Ответ со спарклайнами возвращает requests24h, totalRequests, errorRate и avgLatencyMs.

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

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

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

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

API корзины#

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

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

GET /api/trash

Python SDK: client.lifecycle.trash()

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

Ответ включает items (каждый с daysRemaining), total, page, limit, totalPages и summary с итогами по типам.

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

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, где применимо.

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

Загрузи файл запросом PUT на адрес uploadUrl, используя объявленный тобой Content-Type.

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

POST /api/upload/complete

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

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

Ответ: success и объект file с size и contentType. Для моделей это прикрепляет веса; для архивов датасетов вызови ingest следующим шагом для запуска обработки.

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

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

Список интеграций#

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, которые будут импортированы, количество пропущенных, неподдерживаемых и неразрешенных проектов, 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 keys#

GET /api/api-keys

Python SDK: client.account.api_keys()

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

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

GET /api/storage

Python SDK: client.account.storage()

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

Ответ:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "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"
}

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

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 (ID, статус, расчетный цикл, окончание периода), metrics (лимит хранилища и использование), trainingCredit, features, creditsCents и количество мест.

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

GET /api/billing/transactions

Python SDK: client.billing.transactions()

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

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

Explore API#

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

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

GET /api/explore/search

Python SDK: client.explore.search()

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

Ответ: projects, datasets и hasMore.

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.5" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    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#

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

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

pip install "ultralytics>=8.4.120"

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

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#