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

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

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

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

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

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

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

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

API проектов

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

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

GET /api/projects

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

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

GET /api/projects/{projectId}

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

POST /api/projects

curl -X POST \
  -H "Authorization: Bearer $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"
}

Скачать трек

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

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

Запуск 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
    }
}

Получить токен Predict

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}

Экспорт треков Скачать

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

API активности

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

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

GET /api/activity

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

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

POST /api/activity/mark-seen

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

{
    "all": true
}

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

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

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

POST /api/activity/archive

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

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

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

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

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

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

Для упрощения интеграции используйте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:

Перенос на платформу

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

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"

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

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

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

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

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

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

Существуют ли клиентские библиотеки 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")

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

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

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

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

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

Комментарии