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

Платформа Ultralytics предоставляет комплексный 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. Публичные конечные точки (перечисление общедоступных наборов данных, проектов и моделей) поддерживают анонимный доступ для чтения без ключа.

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

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

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

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

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

Authorization: Bearer ul_your_api_key_here

Пример

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

Базовый URL

Все конечные точки API используют:

https://platform.ultralytics.com/api

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

API использует двухуровневую систему ограничения частоты запросов для защиты от злоупотреблений, сохраняя при этом неограниченное легитимное использование:

• На каждый ключ API — Ограничения применяются для каждого ключа API к аутентифицированным запросам
• По IP-адресу — 100 запросов/мин на IP-адрес для всех /api/* пути (применимо как к аутентифицированным, так и к неаутентифицированным запросам)

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

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

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

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

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

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

{
    "error": "Invalid dataset ID"
}

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

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

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

GET /api/datasets

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

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

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

Ответ:

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

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

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

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

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

GET /api/datasets/{datasetId}/export

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

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

Ответ:

{
    "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-файлов, содержащих изображения и метки.

graph LR
    A[Upload ZIP] --> B[POST /api/datasets/ingest]
    B --> C[Process ZIP]
    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] }]
}

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

Перемещение изображений между разделами (обучающий/валидационный/тестовый) в рамках набора данных:

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 $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

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

PATCH /api/projects/{projectId}

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

DELETE /api/projects/{projectId}

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

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

POST /api/projects/{projectId}/clone

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

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

POST /api/projects/{projectId}/icon

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

DELETE /api/projects/{projectId}/icon

API моделей

Управляйте контрольными точками обученных моделей в проектах.

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

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

Клонировать публичную модель в один из ваших проектов.

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

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

track загрузки

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

track аналитики загрузки моделей.

Запуск Inference

POST /api/models/{modelId}/predict

Многокомпонентная форма:

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

Ответ:

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

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

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

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

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

API обучения

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

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 $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo11n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

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

GET /api/models/{modelId}/training

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

Отменить обучение

DELETE /api/models/{modelId}/training

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

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

Создавайте и управляйте выделенными конечными точками вывода.

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

Приостановить выполняемое развертывание (останавливает тарификацию).

Проверка работоспособности (Health Check)

GET /api/deployments/{deploymentId}/health

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

Выполнить инференс при развертывании

POST /api/deployments/{deploymentId}/predict

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

Многокомпонентная форма:

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

GET /api/deployments/{deploymentId}/metrics

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

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

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

GET /api/deployments/{deploymentId}/logs

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

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

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

GET /api/monitoring

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

API экспорта

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

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

GET /api/exports

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

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

POST /api/exports

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

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

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

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

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

GET /api/exports/{exportId}

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

DELETE /api/exports/{exportId}

track экспорта загрузки

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

API активности

track и управлять событиями активности для вашей учетной записи.

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

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

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

POST /api/billing/portal-session

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

Автопополнение

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

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

GET /api/billing/auto-topup

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

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

PATCH /api/billing/auto-topup

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

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

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

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

GET /api/billing/payment-methods

Создать Setup Intent

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

Пересчитать хранилище

POST /api/storage

Запускает пересчет использования хранилища.

API загрузки

Прямая загрузка файлов использует двухэтапный процесс с подписанными URL.

Получить подписанный 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

GET /api/api-keys

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

POST /api/api-keys

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

{
    "name": "training-server"
}

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

DELETE /api/api-keys

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

Пример:

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

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

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

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

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

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

GET /api/explore/search

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

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

GET /api/explore/sidebar

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

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

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

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

Конечные точки соответствия GDPR для экспорта и удаления данных.

Получить статус задачи 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

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

Использование наборов данных платформы

Ссылки на наборы данных с ul:// URI:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/your-dataset",
    epochs=100,
    imgsz=640,
)

Формат URI:

Загрузка на платформу

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

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://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")

Выполнение инференса:

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/my-dataset")

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

Вебхуки

Веб-хуки уведомляют ваш сервер о событиях платформы посредством HTTP POST колбэков:

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

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

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

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

Конечные точки Активность и Корзина также поддерживают page параметр для постраничной пагинации:

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

Конечная точка поиска «Обзор» использует offset вместо page, с фиксированным размером страницы 20:

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

Можно ли использовать API без SDK?

Да, весь функционал доступен через REST. SDK на python является удобной оболочкой, которая добавляет такие функции, как потоковая передача метрик в реальном времени и автоматическая загрузка моделей.

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

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

Как обрабатывать ограничения скорости запросов?

Используйте 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 моей модели или набора данных?

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

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

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

📅 Создано 2 месяцев назад ✏️ Обновлено 5 дней назад

Комментарии