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

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

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

Обзор API

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

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

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

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

Получить API-ключ

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

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

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

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

Authorization: Bearer YOUR_API_KEY

Пример

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

Базовый URL

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

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

API применяет ограничения частоты запросов на основе API-ключа (скользящее окно, на базе Upstash Redis), чтобы защититься от злоупотреблений, не ограничивая легитимное использование. Анонимный трафик дополнительно защищен средствами контроля злоупотреблений уровня платформы Vercel.

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

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

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

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

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

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

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

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

Ответы об успехе

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

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

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

{
    "error": "Dataset not found"
}

Datasets API

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

Список датасетов

GET /api/datasets

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

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

Ответ:

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

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

GET /api/datasets/{datasetId}

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

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

POST /api/datasets

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

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

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

PATCH /api/datasets/{datasetId}

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

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

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

DELETE /api/datasets/{datasetId}

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

Клонировать набор данных

POST /api/datasets/{datasetId}/clone

Создает копию набора данных со всеми изображениями и разметками. Клонировать можно только публичные наборы данных. Требуется активная сессия браузера на платформе — недоступно через API-ключ.

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

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

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

GET /api/datasets/{datasetId}/export

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

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

Ответ:

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

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

POST /api/datasets/{datasetId}/export

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

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

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

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

Ответ:

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

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

PATCH /api/datasets/{datasetId}/export

Обновить описание существующей версии. Только для владельца.

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

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

Ответ:

{
    "ok": true
}

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

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
}

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

GET /api/datasets/{datasetId}/models

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

Ответ:

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

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

POST /api/datasets/{datasetId}/predict

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

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

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

POST /api/datasets/ingest

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

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

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

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

GET /api/datasets/{datasetId}/images

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

API проектов

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

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

GET /api/projects

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

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

GET /api/projects/{projectId}

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

POST /api/projects

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

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

PATCH /api/projects/{projectId}

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

DELETE /api/projects/{projectId}

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

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

POST /api/projects/{projectId}/clone

Клонируй публичный проект (со всеми его моделями) в свое рабочее пространство. Требуется активная сессия браузера на платформе — недоступно через API-ключ.

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

Загрузи значок проекта (multipart form с файлом изображения):

POST /api/projects/{projectId}/icon

Удалить значок проекта:

DELETE /api/projects/{projectId}/icon

Оба требуют активного сеанса браузера на платформе — недоступно через API-ключ.

API моделей

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

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

GET /api/models

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

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

GET /api/models/completed

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

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

GET /api/models/{modelId}

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

POST /api/models

JSON-тело:

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

PATCH /api/models/{modelId}

Удаление модели

DELETE /api/models/{modelId}

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

GET /api/models/{modelId}/files

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

Клонировать модель

POST /api/models/{modelId}/clone

Клонируй публичную модель в один из своих проектов. Требует активного сеанса браузера на платформе — недоступно через API-ключ.

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

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

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

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

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

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

POST /api/models/{modelId}/predict

Multipart-форма:

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

Ответ:

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

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

POST /api/models/{modelId}/predict/token

Прогрев модели

POST /api/models/{modelId}/predict/warmup

API обучения

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

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

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

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

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

GET /api/models/{modelId}/training

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

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

DELETE /api/models/{modelId}/training

Завершает работающий экземпляр вычислений и помечает задание как отмененное. Требует активного сеанса браузера на платформе — недоступно через API-ключ.

API развертывания

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

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

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

GET /api/deployments

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

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

POST /api/deployments

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

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

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

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

GET /api/deployments/{deploymentId}

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

DELETE /api/deployments/{deploymentId}

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

POST /api/deployments/{deploymentId}/start

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

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

POST /api/deployments/{deploymentId}/stop

Приостановить запущенное развертывание (останавливает биллинг).

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

GET /api/deployments/{deploymentId}/health

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

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

POST /api/deployments/{deploymentId}/predict

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

Multipart-форма:

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

GET /api/deployments/{deploymentId}/metrics

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

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

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

GET /api/deployments/{deploymentId}/logs

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

API мониторинга

Агрегированные метрики

GET /api/monitoring

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

API экспорта

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

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

GET /api/exports

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

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

POST /api/exports

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

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

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

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

GET /api/exports/{exportId}

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

DELETE /api/exports/{exportId}

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

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

API активности

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

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

GET /api/activity

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

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

POST /api/activity/mark-seen

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

{
    "all": true
}

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

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

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

POST /api/activity/archive

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

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

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

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

API корзины

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

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

GET /api/trash

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

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

POST /api/trash

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

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

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

DELETE /api/trash

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

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

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

DELETE /api/trash/empty

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

API биллинга

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

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

GET /api/billing/balance

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

Ответ:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

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

GET /api/billing/usage-summary

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

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

GET /api/billing/transactions

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

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

Создать сессию оплаты

POST /api/billing/checkout-session

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

{
    "amount": 25,
    "owner": "team-username"
}

Создает сессию оплаты для покупки кредитов.

Создать оплату подписки

POST /api/billing/subscription-checkout

Создает сессию оплаты для перехода на подписку Pro.

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

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

Отмена или возобновление подписки

DELETE /api/billing/subscription-checkout

По умолчанию отменяет подписку Pro в конце периода. Отправь {"resume": true}, чтобы возобновить уже запланированную отмену до окончания биллингового периода.

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

{
    "resume": true
}

Автоматическое пополнение

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

Получить конфигурацию автопополнения

GET /api/billing/auto-topup

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

Обновить конфигурацию автопополнения

PATCH /api/billing/auto-topup

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

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

Способы оплаты

Список способов оплаты

GET /api/billing/payment-methods

Создать намерение настройки

POST /api/billing/payment-methods/setup

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

Установить способ оплаты по умолчанию

POST /api/billing/payment-methods/default

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

{
    "paymentMethodId": "pm_123"
}

Обновить платежную информацию

PATCH /api/billing/payment-methods

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

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

Удалить способ оплаты

DELETE /api/billing/payment-methods/{id}

API хранилища

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

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

GET /api/storage

Ответ:

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

API загрузки

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

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

POST /api/upload/signed-url

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

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

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

Ответ:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

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

POST /api/upload/complete

Уведомь платформу о завершении загрузки файла, чтобы она могла начать обработку.

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

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API ключей API

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

Список API ключей

GET /api/api-keys

Создать API ключ

POST /api/api-keys

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

{
    "name": "training-server"
}

Удалить API ключ

DELETE /api/api-keys

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

Пример:

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

API команд и участников

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

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

GET /api/teams

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

POST /api/teams/create

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

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

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

GET /api/members

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

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

POST /api/members

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

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

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

PATCH /api/members/{userId}

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

DELETE /api/members/{userId}

Передать право собственности

POST /api/members/transfer-ownership

Приглашения

Принять приглашение

POST /api/invites/accept

Получить информацию о приглашении

GET /api/invites/info

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

Отозвать приглашение

DELETE /api/invites/{inviteId}

Отправить приглашение повторно

POST /api/invites/{inviteId}/resend

API исследования (Explore)

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

Поиск публичного контента

GET /api/explore/search

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

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

GET /api/explore/sidebar

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

API пользователей и настроек

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

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

GET /api/users

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

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

PATCH /api/users

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

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

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

GET /api/username/check

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

Настройки

GET /api/settings
POST /api/settings

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

Значок профиля

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

Загрузи или удали аватар профиля.

Онбординг

POST /api/onboarding

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

API GDPR

Запроси экспорт всех своих данных или навсегда удали свою учетную запись. См. Settings documentation.

Получить статус задачи GDPR

GET /api/gdpr

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

Возвращает статус задачи. Для завершенных задач экспорта ответ включает downloadUrl.

Начать процесс экспорта или удаления

POST /api/gdpr

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

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

Опционально для командных рабочих пространств:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

Коды ошибок

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

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

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

pip install ultralytics

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

yolo check

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

yolo settings api_key=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:

Отправка на Platform

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

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

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

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

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

Запуск вывода (inference):

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, half=True)

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

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

Валидация:

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

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

Вебхуки

Platform использует внутренние вебхуки для передачи метрик обучения в реальном времени из Python SDK ultralytics (работающего на облачных GPU или удаленных/локальных машинах) обратно на Platform — loss по эпохам, mAP, системную статистику и статус завершения. Эти вебхуки проходят аутентификацию через HMAC webhookSecret, предоставленный для каждой задачи обучения, и не предназначены для использования пользовательскими приложениями.

FAQ

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

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

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

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

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

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

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

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

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

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

В настоящий момент используй пакет Ultralytics для Python или выполняй прямые HTTP-запросы. Официальные клиентские библиотеки для других языков запланированы.

Как обрабатывать лимиты запросов (rate limits)?

Используй заголовок 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 Exception("Rate limit exceeded")

Как найти ID моей модели или набора данных?

ID ресурсов возвращаются при создании ресурсов через API. Ты также можешь найти их в URL платформы:

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

Используй эндпоинты списка (list endpoints) для поиска по имени или фильтрации по проекту.