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] --> 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

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

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

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-эндпоинты используют:

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

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

При превышении лимита 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Выделенные эндпоинты (безлимитные)#

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

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}

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

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

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

PATCH /api/datasets/{datasetId}

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

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

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

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

POST /api/datasets/{datasetId}/icon

Удали значок набора данных:

DELETE /api/datasets/{datasetId}/icon

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

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

DELETE /api/datasets/{datasetId}

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

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

POST /api/datasets/{datasetId}/clone

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

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

{
    "name": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "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Получить статистику классов#

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

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

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

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

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

Переназначение изображений между выборками train/val/test. Все три операции требуют активной сессии браузера на платформе — недоступно через API-ключ.

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

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

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

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]

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

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

GET /api/datasets/{datasetId}/images

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

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

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

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

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

POST /api/projects/{projectId}/icon

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

DELETE /api/projects/{projectId}/icon

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

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

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

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

GET /api/models

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

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

GET /api/models/completed

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

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

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

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

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

Multipart Form:

Максимальный размер загрузки составляет 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

Ответ:

{
    "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 sectionПолучить токен предсказания#

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

Link to this sectionПрогрев модели#

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

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

Запускай обучение 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]

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

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

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

DELETE /api/models/{modelId}/training

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

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

Развертывай модели на выделенных эндпоинтах инференса с проверками работоспособности и мониторингом. Новые развертывания по умолчанию используют масштабирование до нуля, 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]

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:

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

GET /api/deployments/{deploymentId}/metrics

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

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

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

GET /api/deployments/{deploymentId}/logs

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

Link to this sectionAPI мониторинга#

Link to this sectionАгрегированные метрики#

GET /api/monitoring

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

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

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

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

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

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

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

POST /api/activity/archive

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

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

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

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

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 биллинга#

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

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

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

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

Link to this sectionСоздать сеанс оформления заказа#

POST /api/billing/checkout-session

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

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

Создает сеанс оформления заказа для покупки кредитов.

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

POST /api/billing/subscription-checkout

Создает сеанс оформления заказа для обновления до Pro-подписки.

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

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

Link to this sectionОтменить или возобновить подписку#

DELETE /api/billing/subscription-checkout

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

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

{
    "resume": true
}

Link to this sectionАвтоматическое пополнение#

Автоматически пополняй баланс при падении ниже установленного порога.

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

GET /api/billing/auto-topup

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

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

PATCH /api/billing/auto-topup

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

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

Link to this sectionСпособы оплаты#

Link to this sectionСписок способов оплаты#

GET /api/billing/payment-methods

Link to this sectionСоздать Setup Intent#

POST /api/billing/payment-methods/setup

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

Link to this sectionУстановить способ оплаты по умолчанию#

POST /api/billing/payment-methods/default

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

{
    "paymentMethodId": "pm_123"
}

Link to this sectionОбновить платежную информацию#

PATCH /api/billing/payment-methods

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

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

Link to this sectionУдалить способ оплаты#

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

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 sectionUpload API#

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

Link to this sectionПолучить подписанный 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/...",
    "gcsPath": "gs://bucket/users/user123/images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

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

POST /api/upload/complete

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

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

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

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 sectionПриглашения#

Link to this sectionПринять приглашение#

POST /api/invites/accept

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

GET /api/invites/info

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

Link to this sectionОтозвать приглашение#

DELETE /api/invites/{inviteId}

Link to this sectionОтправить приглашение повторно#

POST /api/invites/{inviteId}/resend

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 keys, использованием хранилища и настройками конфиденциальности данных. См. Settings documentation.

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

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

Link to this sectionОнбординг#

POST /api/onboarding

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

Link to this sectionGDPR API#

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

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

GET /api/gdpr

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

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

Link to this sectionНачать процесс экспорта или удаления#

POST /api/gdpr

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

{
    "action": "export"
}

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

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

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

Link to this sectionКоды ошибок#

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

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

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

pip install ultralytics

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

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

Link to this sectionВебхуки#

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

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 — это удобная обертка, добавляющая такие функции, как потоковая передача метрик в реальном времени и автоматическая загрузка моделей. Ты также можешь изучить все эндпоинты в интерактивном режиме на 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 Exception("Rate limit exceeded")

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

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

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

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