Справочник по 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 YOUR_API_KEY

Пример

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

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
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 YOUR_API_KEY" },
});
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": "Dataset not found"
}

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

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

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

GET /api/datasets

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

curl -H "Authorization: Bearer YOUR_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 или 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] }]
}

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

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

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

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 моделей

Управляйте обученными моделями 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

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

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

{
    "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 YOUR_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 обучения

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

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

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": "yolo26n.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 экспорта

Преобразуйте модели в оптимизированные форматы, такие как 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

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 активности

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

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

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-адреса, затем загрузка файла. См. документацию по данным.

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

Список ключей 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 команд и участников

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

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

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 пользователя и настроек

Управляйте своим профилем, ключами 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

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("yolo26n.pt")

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

Формат URI:

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

Отправка результатов в проект 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")

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

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

Вебхуки

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

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

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

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

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

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

curl -H "Authorization: Bearer YOUR_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. Python SDK — это удобная обертка, которая добавляет такие функции, как потоковая передача метрик в реальном времени и автоматическая загрузка моделей. Вы также можете интерактивно изучить все конечные точки по адресу platform.ultralytics.com/api/docs.

Существуют ли клиентские библиотеки 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 месяцев назад ✏️ Обновлено 2 дней назад

Комментарии