Link to this sectionСправочник REST API#

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

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

Link to this sectionОбзор API#

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

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

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

Link to this sectionАутентификация#

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

Link to this sectionПолучение API-ключа#

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

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

Link to this sectionЗаголовок авторизации#

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

Authorization: Bearer YOUR_API_KEY

Link to this sectionПример#

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

Link to this sectionБазовый URL#

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

https://platform.ultralytics.com/api

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

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

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

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

Link to this sectionЛимиты на API-ключ#

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

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

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

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

Link to this sectionФормат ответа#

Link to this sectionУспешные ответы#

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

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

Link to this sectionОтветы об ошибках#

{
    "error": "Dataset not found"
}

Link to this sectionAPI наборов данных#

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

Link to this sectionСписок наборов данных#

GET /api/datasets

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

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

Ответ:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

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

GET /api/datasets/{datasetId}

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

Передай username, когда {datasetId} является слагом набора данных, а не ID.

Link to this sectionСоздать набор данных#

POST /api/datasets

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

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

Ответ:

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

Link to this sectionОбновить набор данных#

PATCH /api/datasets/{datasetId}

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

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

Link to this sectionЗначок набора данных#

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

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

Link to this sectionУдалить набор данных#

DELETE /api/datasets/{datasetId}

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

Link to this sectionКлонирование набора данных#

POST /api/datasets/{datasetId}/clone

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

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

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

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

GET /api/datasets/{datasetId}/export

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

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

Ответ:

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

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

POST /api/datasets/{datasetId}/export

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

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

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

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

Ответ:

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

Link to this sectionОбновить описание версии#

PATCH /api/datasets/{datasetId}/export

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

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

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

Ответ:

{
    "ok": true
}

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

POST /api/datasets/{datasetId}/restore

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

{
    "version": 2
}

Link to this sectionПолучить статистику классов#

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

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

Ответ:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

Link to this sectionУправление классами#

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

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

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

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

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

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

{
    "classIds": [2, 4]
}

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

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

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

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

Link to this sectionЭмбеддинги набора данных#

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

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

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

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

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

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

GET /api/datasets/{datasetId}/models

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

Ответ:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

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

POST /api/datasets/{datasetId}/predict

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

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

Link to this sectionЗагрузка набора данных#

POST /api/datasets/ingest

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

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

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

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

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

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

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

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

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

Ответ:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/ingest]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

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

Link to this sectionИзображения набора данных#

Link to this sectionСписок изображений#

GET /api/datasets/{datasetId}/images

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

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

POST /api/datasets/{datasetId}/images

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

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

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

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

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

Link to this sectionУдалить изображение#

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

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

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

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

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

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

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

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

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

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

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

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

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

Link to this sectionAPI проектов#

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

Link to this sectionСписок проектов#

GET /api/projects

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

Link to this sectionПолучить проект#

GET /api/projects/{projectId}

Link to this sectionСоздать проект#

POST /api/projects

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

Link to this sectionОбновить проект#

PATCH /api/projects/{projectId}

Link to this sectionУдалить проект#

DELETE /api/projects/{projectId}

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

Link to this sectionКлонировать проект#

POST /api/projects/{projectId}/clone

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

Link to this sectionЗначок проекта#

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

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

Link to this sectionAPI моделей#

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

Link to this sectionСписок моделей#

GET /api/models

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

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

GET /api/models/completed

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

Link to this sectionПолучить модель#

GET /api/models/{modelId}

Link to this sectionСоздать модель#

POST /api/models

JSON тело:

Link to this sectionОбновить модель#

PATCH /api/models/{modelId}

Link to this sectionУдалить модель#

DELETE /api/models/{modelId}

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

GET /api/models/{modelId}/files

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

Link to this sectionКлонирование модели#

POST /api/models/{modelId}/clone

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

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

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

Link to this sectionОтслеживать скачивания#

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

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

Link to this sectionЗапусти вывод#

POST /api/models/{modelId}/predict

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

Multipart Form:

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

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

Ответ:

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

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

Link to this sectionAPI обучения#

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

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

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

Link to this sectionНачать обучение#

POST /api/training/start

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

Link to this sectionПолучить доступность GPU#

GET /api/training/gpu-availability

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

Link to this sectionПолучить статус обучения#

GET /api/models/{modelId}/training

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

Link to this sectionОтменить обучение#

DELETE /api/models/{modelId}/training

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

Link to this sectionAPI развертываний#

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

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

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

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

GET /api/deployments

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

Link to this sectionСоздать развертывание#

POST /api/deployments

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

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

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

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

GET /api/deployments/{deploymentId}

Link to this sectionУдалить развертывание#

DELETE /api/deployments/{deploymentId}

Link to this sectionЗапустить развертывание#

POST /api/deployments/{deploymentId}/start

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

Link to this sectionОстановить развертывание#

POST /api/deployments/{deploymentId}/stop

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

Link to this sectionПроверка работоспособности#

GET /api/deployments/{deploymentId}/health

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

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

POST /api/deployments/{deploymentId}/predict

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

Multipart Form:

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

Link to this sectionПолучить метрики#

GET /api/deployments/{deploymentId}/metrics

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

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

Link to this sectionПолучить логи#

GET /api/deployments/{deploymentId}/logs

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

Link to this sectionAPI экспорта#

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

Link to this sectionСписок экспортов#

GET /api/exports

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

Link to this sectionСоздать экспорт#

POST /api/exports

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

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

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

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

Link to this sectionПолучить статус экспорта#

GET /api/exports/{exportId}

Link to this sectionОтменить экспорт#

DELETE /api/exports/{exportId}

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

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

Link to this sectionAPI активности#

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

Link to this sectionСписок активности#

GET /api/activity

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

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

POST /api/activity/mark-seen

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

{
    "all": true
}

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

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

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

Link to this sectionАрхивировать события#

POST /api/activity/archive

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

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

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

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

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

Link to this sectionAPI корзины#

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

Link to this sectionСписок корзины#

GET /api/trash

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

Link to this sectionВосстановить элемент#

POST /api/trash

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

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

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

DELETE /api/trash

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

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

Link to this sectionОчистить корзину#

DELETE /api/trash/empty

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

Link to this sectionAPI биллинга#

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

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

Link to this sectionПолучить баланс#

GET /api/billing/balance

Ответ:

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

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

GET /api/billing/usage-summary

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

Link to this sectionПолучить транзакции#

GET /api/billing/transactions

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

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

Link to this sectionStorage API#

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

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

GET /api/storage

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

Ответ:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

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

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

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

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

Link to this sectionUpload API#

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

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

POST /api/upload/signed-url

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

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

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

Ответ:

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

Link to this sectionЗавершить загрузку#

POST /api/upload/complete

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

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

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

Link to this sectionAPI интеграций#

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

Link to this sectionПредпросмотр импорта из Roboflow#

POST /api/integrations/roboflow/preview

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

Link to this sectionИмпорт из Roboflow#

POST /api/integrations/roboflow/import

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

Link to this sectionAPI Keys API#

Управляй своими API keys для программного доступа. См. API Keys documentation.

Link to this sectionСписок API keys#

GET /api/api-keys

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

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

Link to this sectionСоздать API key#

POST /api/api-keys

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

{
    "name": "training-server"
}

Link to this sectionУдалить API key#

DELETE /api/api-keys

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

Пример:

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

Link to this sectionTeams & Members API#

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

Link to this sectionСписок команд#

GET /api/teams

Link to this sectionСоздать команду#

POST /api/teams/create

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

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

Link to this sectionСписок участников#

GET /api/members

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

Link to this sectionПригласить участника#

POST /api/members

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

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

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

PATCH /api/members/{userId}

Link to this sectionУдалить участника#

DELETE /api/members/{userId}

Link to this sectionПередача прав владения#

POST /api/members/transfer-ownership

Link to this sectionExplore API#

Ищи и просматривай общедоступные наборы данных и проекты, которыми делится сообщество. См. Explore documentation.

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

GET /api/explore/search

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

Link to this sectionДанные боковой панели#

GET /api/explore/sidebar

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

Link to this sectionUser & Settings APIs#

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

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

GET /api/account/summary

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

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

GET /api/users

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

Link to this sectionПодписаться или отписаться от пользователя#

PATCH /api/users

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

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

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

GET /api/username/check

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

Link to this sectionНастройки#

GET /api/settings
POST /api/settings

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

Link to this sectionИконка рабочей области#

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

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

Link to this sectionИнтеграция с Python#

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

Link to this sectionУстановка и настройка#

pip install "ultralytics>=8.4.104"

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

yolo check

Link to this sectionАутентификация#

yolo settings api_key=YOUR_API_KEY

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

Ссылайся на датасеты с помощью 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:

Link to this sectionОтправка на платформу#

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

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

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

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

Link to this sectionПримеры 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}")

Link to this sectionFAQ#

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

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

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

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

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

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

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

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

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

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

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

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

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

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise RuntimeError("Rate limit exceeded")

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

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

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

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