Перейти к содержанию

REST API

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

Быстрый старт

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

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

Все запросы API требуют аутентификации с помощью ключа API.

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

  1. Перейдите в «Настройки» > «Ключи API».
  2. Нажмите «Создать ключ»
  3. Скопируйте сгенерированный ключ

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

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

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

Authorization: Bearer ul_your_api_key_here

Пример

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

Базовый URL

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

https://platform.ultralytics.com/api

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

ПланЗапросы/МинутаЗапросы/день
Бесплатно601,000
Pro30050,000
ПредприятиеПользовательскийПользовательский

В ответах включаются заголовки ограничения скорости:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

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

Все ответы представлены в формате JSON:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

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

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

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

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

GET /api/datasets

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

ПараметрТипОписание
pageintНомер страницы (по умолчанию: 1)
limitintЭлементов на странице (по умолчанию: 20)
taskстрокаФильтр по типу задачи

Ответ:

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

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

GET /api/datasets/{datasetId}

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

POST /api/datasets

Тело:

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

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

DELETE /api/datasets/{datasetId}

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

POST /api/datasets/{datasetId}/export

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

API проектов

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

GET /api/projects

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

GET /api/projects/{projectId}

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

POST /api/projects

Тело:

{
    "name": "my-project",
    "description": "Detection experiments"
}

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

DELETE /api/projects/{projectId}

Модели API

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

GET /api/models

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

ПараметрТипОписание
projectIdстрокаФильтр по проекту
taskстрокаФильтр по типу задачи

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

GET /api/models/{modelId}

Загрузить модель

POST /api/models

Многочастная форма:

ПолеТипОписание
fileфайлаФайл модели .pt
projectIdстрокаЦелевой проект
nameстрокаНазвание модели

Удалить модель

DELETE /api/models/{modelId}

Скачать модель

GET /api/models/{modelId}/files

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

Запуск Inference

POST /api/models/{modelId}/predict

Многочастная форма:

ПолеТипОписание
fileфайлаФайл изображения
confплавающийПорог достоверности
iouплавающийIoU

Ответ:

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

API обучения

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

POST /api/training/start

Тело:

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

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

GET /api/models/{modelId}/training

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

DELETE /api/models/{modelId}/training

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

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

GET /api/deployments

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

ПараметрТипОписание
modelIdстрокаФильтровать по модели

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

POST /api/deployments

Тело:

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

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

GET /api/deployments/{deploymentId}

Начать развертывание

POST /api/deployments/{deploymentId}/start

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

POST /api/deployments/{deploymentId}/stop

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

DELETE /api/deployments/{deploymentId}

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

GET /api/deployments/{deploymentId}/metrics

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

GET /api/deployments/{deploymentId}/logs

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

ПараметрТипОписание
severityстрокаИНФОРМАЦИЯ, ПРЕДУПРЕЖДЕНИЕ, ОШИБКА
limitintКоличество записей

Экспорт API

Экспорт списков

GET /api/exports

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

POST /api/exports

Тело:

{
    "modelId": "model_abc123",
    "format": "onnx"
}

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

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

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

GET /api/exports/{exportId}

API активности

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

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

GET /api/activity

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

ПараметрТипОписание
startDateстрокаФильтр по дате (ISO)
endDateстрокаФильтр по дате (ISO)
searchстрокаПоиск в сообщениях о событиях

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

POST /api/activity/mark-seen

Архив событий

POST /api/activity/archive

API для мусора

Управление временно удаленными ресурсами (хранение в течение 30 дней).

Список мусора

GET /api/trash

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

POST /api/trash

Тело:

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

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

POST /api/trash/empty

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

API для выставления счетов

Управление кредитами и подписками.

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

GET /api/billing/balance

Ответ:

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

Микро-доллар США

Все суммы указаны в микро-долларах США (1 000 000 = 1,00 доллар США) для точного учета.

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

GET /api/billing/usage-summary

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

Создать сеанс оформления заказа

POST /api/billing/checkout-session

Тело:

{
    "amount": 25
}

Создает сессию Stripe checkout для покупки в кредит (5–1000 долларов).

Создать подписку Оформить заказ

POST /api/billing/subscription-checkout

Создает сессию Stripe checkout для подписки Pro.

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

POST /api/billing/portal-session

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

Получить историю платежей

GET /api/billing/payments

Возвращает список платежных транзакций из Stripe.

API хранения

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

GET /api/storage

Ответ:

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

GDPR API

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

Экспорт/удаление данных учетной записи

POST /api/gdpr

Тело:

{
    "action": "export"
}
ДействиеОписание
exportСкачать все данные учетной записи
deleteУдалить учетную запись и все данные

Необратимое действие

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

Ключи API API

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

GET /api/api-keys

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

POST /api/api-keys

Тело:

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

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

DELETE /api/api-keys/{keyId}

Коды ошибок

КодОписание
UNAUTHORIZEDНедействительный или отсутствующий ключ API
FORBIDDENНедостаточные права доступа
NOT_FOUNDРесурс не найден
VALIDATION_ERRORНедопустимые данные запроса
RATE_LIMITEDСлишком много запросов
INTERNAL_ERRORОшибка сервера

Поддержка SDK

Для упрощения интеграции используйтеPython Ultralytics Python .

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

Для интеграции с платформой требуется ultralytics>= 8.4.0. Более ранние версии НЕ будут работать с платформой.

pip install "ultralytics>=8.4.0"

import os

from ultralytics import YOLO

# Set API key
os.environ["ULTRALYTICS_API_KEY"] = "ul_your_key"

# Train with Platform integration
model = YOLO("yolo11n.pt")
model.train(data="ul://username/datasets/my-dataset", project="username/my-project", name="experiment-1", epochs=100)

Веб-хуки

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

СобытиеОписание
training.startedНачало обучения
training.epochЭпоха завершена
training.completedОбучение завершено
training.failedОбучение не удалось
export.completedГотов к экспорту

Настройка веб-хуков доступна в тарифных планах Enterprise.

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

Как разбить на страницы большие результаты?

Используйте page и limit параметры:

GET /api/datasets?page=2 &
limit=50

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

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

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

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

Как работать с ограничениями скорости?

Реализовать экспоненциальный откат:

import time


def api_request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url)
        if response.status_code != 429:
            return response
        wait = 2**attempt
        time.sleep(wait)
    raise Exception("Rate limit exceeded")


📅 Создано 0 дней назад ✏️ Обновлено 0 дней назад
glenn-jocher

Комментарии