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

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/datasets/YOUR_USERNAMEДля каждой конечной точки ниже указан вызов client.<resource>.<method>(...) из SDK ultralytics-platform, который создается на основе того же контракта, что и этот справочник.
На этой странице представлен обзор API. Актуальный сгенерированный справочник доступен по адресу platform.ultralytics.com/api/docs, а машиночитаемый документ OpenAPI 3.2, на котором он основан, опубликован по адресу platform.ultralytics.com/openapi.json. Оба документа создаются непосредственно на основе контракта на стороне сервера, поэтому в случае расхождения этой страницы со схемой приоритет имеет контракт.
Обзор API#
API организован вокруг основных ресурсов Platform:
| Ресурс | Описание | Основные операции |
|---|---|---|
| Датасеты | Коллекции размеченных изображений | CRUD, импорт, версии, классы, разделы, клонирование, копирование |
| Изображения | Отдельные изображения и разметка | Чтение, аннотирование, перемещение между разделами, удаление, автоматическое аннотирование, размытие лиц |
| Проекты | Рабочие пространства моделей | CRUD, клонирование |
| Модели | Сохраненные контрольные точки | CRUD, предсказание, скачивание, клонирование, статус обучения |
| Обучение | Задания обучения на облачных GPU | Доступность GPU, запуск, ход выполнения, отмена |
| Экспорт | Задания преобразования формата | Создать, список, статус, отменить, мобильная ссылка |
| Развертывания | Выделенные конечные точки инференса | Создание, обновление, запуск/остановка, предсказание, метрики, журналы |
| Агенты | Сохраненные визуальные рабочие процессы | Просмотр списка, сохранение, удаление |
| Корзина | Ресурсы, удаленные безвозвратно не окончательно | Просмотр списка, восстановление, окончательное удаление |
| Хранилище | Интеграции с облачными хранилищами | Подключение, поиск, просмотр, отключение |
| Аккаунт | Тариф, кредиты, хранилище, профиль | Сводка аккаунта, API-ключи, использование хранилища, поиск пользователей |
| Оплата | Использование тарифа и журнал операций | Сводка использования, транзакции |
| Обзор | Поиск публичного контента | Ищи проекты, датасеты, модели и изображения |
Аутентификация#
Для большинства конечных точек требуется API-ключ. Конечные точки, предоставляющие доступ к публичному контенту — например, чтение публичного датасета, проекта или модели, просмотр списка изображений публичного датасета, запуск инференса на публичной модели или поиск в Explore, — также принимают анонимные запросы и просто возвращают больше данных, если передан ключ.
Получение API-ключа#
- Перейди в
Settings>API Keys - Нажми
Add Key, оставьUltralyticsв качестве провайдера, введи имя и нажмиCreate Key - Скопируй созданный ключ
Подробные инструкции см. в разделе API Keys.
Заголовок авторизации#
Передавай API-ключ в виде токена Bearer:
Authorization: Bearer YOUR_API_KEYКлючи API состоят из буквального префикса ul_ и 40 шестнадцатеричных символов; всего 43 символа (например, ul_a1b2c3d4e5f6789012345678901234567890abcd). Запросы без заголовка, с некорректным или отозванным ключом возвращают 401. Храни ключ в секрете — никогда не добавляй его в систему контроля версий и не публикуй.
Пример#
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/account/summaryБазовый URL#
Для всех конечных точек API используется:
https://platform.ultralytics.com/apiПути к ресурсам#
Большинство ресурсов доступны по тем же понятным человеку именам, что и в URL Platform, а не по идентификаторам базы данных:
| Ресурс | Путь | Пример |
|---|---|---|
| Датасет | /api/datasets/{owner}/{dataset} | /api/datasets/acme-vision/warehouse |
| Проект | /api/projects/{owner}/{project} | /api/projects/acme-vision/inspection |
| Модель | /api/models/{owner}/{project}/{model} | /api/models/acme-vision/inspection/v3 |
| Развёртывание | /api/deployments/{owner}/{deployment} | /api/deployments/acme-vision/edge-1 |
| Изображение | /api/images/{imageId} | /api/images/65f1c0a2b3d4e5f601234567 |
| Агент | /api/workflows?id={agentId} | /api/workflows?id=65f1c0a2b3d4e5f601234567 |
{owner}— это имя пользователя или идентификатор командного рабочего пространства: от 4 до 32 символов, строчные буквы и цифры, сегменты разделяются одиночными дефисами.{dataset},{project},{model}и{deployment}соответствуют тому же формату: строчные буквы и дефисы, не более 128 символов.{imageId},{exportId}и{agentId}— это 24-символьные шестнадцатеричные идентификаторы, возвращаемые API.- При переименовании ресурса через
PATCHодновременно меняются отображаемое имяnameи имя в URL; в ответе возвращается текущее имя в URL, чтобы ты мог продолжать использовать его.
За исключением Agents API, параметра запроса owner нет. В путях к ресурсам в рамках рабочего пространства указан владелец, а конечные точки в рамках аккаунта (/api/account/summary, /api/api-keys, /api/storage, /api/billing/*, /api/trash, /api/integrations/buckets) работают с рабочим пространством, выпустившим API-ключ. Чтобы выполнять действия в командном рабочем пространстве, используй созданный в нем API-ключ или передай owner в Agents API.
Ограничения частоты запросов#
API ограничивает частоту запросов для каждого API-ключа по скользящему окну. Каждый маршрут относится к одной категории, и для каждой категории ведется отдельный счетчик, поэтому 20 запросов predict не расходуют лимит по умолчанию.
| Категория | Ограничение | Применяется к |
|---|---|---|
| По умолчанию | 100 запросов/мин | Все маршруты, не перечисленные ниже |
| Обучение | 10 запросов/мин | POST /api/training/start |
| Загрузка | 10 запросов/мин | Подписанные URL для загрузки, завершение загрузки и импорт датасетов |
| Прогнозирование | 20 запросов/мин | Инференс моделей и развертываний через маршруты Platform API |
| Экспорт | 20 запросов/мин | Просмотр списка и создание экспортов моделей, а также создание и обновление версий датасетов; чтение экспорта датасета (GET) и отдельного экспорта модели используют лимит по умолчанию |
| Скачать | 30 запросов/мин | Скачивание файлов моделей |
| Изменение | 10 запросов/мин | Просмотр списка API-ключей, просмотр списка или подключение интеграций с облачными хранилищами, поиск мест хранения и обновление развертываний (PATCH) |
| Гидратация | 20 запросов/мин | POST /api/datasets/{owner}/{dataset}/images (получение выбранного набора изображений) и GET /api/images/{imageId}/similar |
| Кластеризация | 10 запросов/мин | GET /api/datasets/{owner}/{dataset}/images/clustering и GET /api/models/{owner}/{project}/{model}/similar-images |
Для маршрутов платформы, доступных только через браузер, например оформления оплаты и управления командой, действуют собственные ограничения, которые не распространяются на запросы с API-ключом.
При превышении лимита API возвращает 429 в заголовках и теле JSON:
Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z{
"error": "Rate limit exceeded, wait 12s",
"retryAfter": 12,
"resetAt": "2026-02-21T12:34:56.000Z"
}Выделенные конечные точки (без ограничений)#
На выделенные конечные точки не распространяются ограничения частоты запросов к API платформы по API-ключу, если обращаться напрямую к serviceUrl самого развертывания (например, https://predict-abc123.run.app/predict). В этом случае пропускная способность зависит от конфигурации развернутого сервиса.
Получив 429, подожди Retry-After секунд (или до X-RateLimit-Reset), прежде чем повторить запрос. Реализацию экспоненциальной задержки перед повторными запросами см. в FAQ по ограничениям частоты запросов.
Формат ответа#
Успешные ответы#
Ответы представляют собой JSON-объекты с полями, зависящими от ресурса. Общей оболочки нет: конечные точки для получения списков возвращают именованную коллекцию, обычно вместе с количеством элементов, а операции изменения — измененные идентификаторы.
{
"datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
"total": 1,
"region": "us"
}Списки ресурсов, ответы на создание и клонирование, а также некоторые ответы на запросы, например о развертываниях, хранилище и корзине, также содержат region (us, eu или ap) — регион хранения для этой рабочей области.
Ответы с ошибками#
Каждый ответ с ошибкой — это JSON-объект с сообщением error:
{
"error": "Dataset not found"
}| Статус HTTP | Значение |
|---|---|
200 | Успешно |
201 | Создана |
202 | Принято, обработка продолжается асинхронно |
400 | Недопустимый путь, запрос или тело запроса |
401 | Отсутствует или недействителен токен аутентификации |
402 | Недостаточно кредитов (обучение) |
403 | Недостаточно прав, не подходит тарифный план или превышена квота |
404 | Ресурс не найден |
409 | Конфликт с текущим состоянием (дублирующееся имя, выполняющееся задание) |
413 | Входные данные для предсказания слишком велики |
422 | Классы модели не соответствуют набору данных или ключ поставщика отсутствует либо отклонен (автоматическая разметка) |
429 | Превышен лимит частоты запросов |
500 | Ошибка сервера |
502 | Не удалось выполнить вызов вышестоящего поставщика или сервиса |
503 | Зависимый сервис временно недоступен |
Пагинация#
Способ пагинации зависит от коллекции:
| Способ | Конечные точки | Параметры |
|---|---|---|
| Только лимит | Списки наборов данных, проектов, моделей, экспортов и развертываний | limit |
| Смещение и лимит | Изображения набора данных, кластеризация изображений, поиск в Explore | offset, limit, а также hasMore в ответе |
| Курсор | Изображения набора данных (большие наборы данных) | cursor, includeTotal, а также nextCursor |
| Номер страницы | Корзина | page, limit, а также totalPages |
| Непрозрачный токен страницы | Журналы развертывания | pageToken, а также nextPageToken |
API наборов данных#
Создавай, просматривай и управляй размеченными наборами изображений для обучения моделей YOLO. См. документацию по наборам данных.
Список наборов данных#
GET /api/datasets/{owner}Python SDK: client.datasets.list(owner)
Возвращает общедоступные наборы данных владельца, а также закрытые наборы данных, если твой ключ позволяет просматривать эту рабочую область.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
limit | int | Максимальное количество возвращаемых наборов данных (по умолчанию: 1000, макс.: 1000) |
includeSamples | логическое значение | Включить предварительный просмотр примеров изображений (по умолчанию: true) |
includeImageUrls | логическое значение | Включить URL резервных полноразмерных примеров изображений (по умолчанию: false) |
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://platform.ultralytics.com/api/datasets/acme-vision?limit=10&includeSamples=false"Ответ:
{
"datasets": [
{
"id": "65f1c0a2b3d4e5f601234567",
"owner": "acme-vision",
"dataset": "warehouse",
"name": "Warehouse",
"task": "detect",
"visibility": "private",
"imageCount": 1000,
"classCount": 2,
"classNames": ["person", "forklift"],
"splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
"annotationCount": 5400,
"starCount": 3,
"isStarred": false,
"status": "ready",
"createdAt": "2026-01-15T10:00:00Z",
"updatedAt": "2026-01-16T08:30:00Z"
}
],
"total": 1,
"region": "us"
}Получить набор данных#
GET /api/datasets/{owner}/{dataset}Python SDK: client.datasets.retrieve(owner, dataset)
Возвращает полный объект набора данных под ключом dataset, включая classNames, splits, versions, source и пользовательский объект metadata. Пока обрабатывается импорт 10 000 или более изображений, редакторы также получают processingProgress с stage, percent и, если они известны, processed, total и objects (просканированные облачные объекты).
Создать набор данных#
POST /api/datasetsPython SDK: client.datasets.create(dataset=..., name=...)
Тело запроса:
{
"dataset": "warehouse",
"name": "Warehouse",
"task": "detect",
"description": "Forklift and pedestrian safety dataset",
"classNames": ["person", "forklift"],
"visibility": "private",
"metadata": { "location": "factory-1", "reviewed": true },
"owner": "acme-vision"
}| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
dataset | строка | Да | Имя набора данных для URL платформы (строчные буквы, слова через дефис, не более 128 символов) |
name | строка | Да | Отображаемое имя (не более 100 символов) |
description | строка | Нет | Описание (не более 1000 символов) |
task | строка | Нет | Тип задачи (по умолчанию: detect) |
classNames | массив | Нет | Названия классов в порядке индекса (максимум 25 000); без дубликатов, совпадения без учета регистра для названий длиной более 2 символов |
format | строка | Нет | Формат аннотаций: yolo (по умолчанию), coco, raw, ndjson |
visibility | строка | Нет | public или private (по умолчанию: видимость по умолчанию рабочего пространства) |
blurFaces | логическое значение | Нет | Размывать лица на изображениях, загруженных в набор данных (см. Размытие лиц) |
tags | массив | Нет | До 50 тегов длиной не более 50 символов каждый |
license | строка | Нет | Идентификатор лицензии набора данных |
metadata | объект | Нет | Пользовательские метаданные JSON |
owner | строка | Нет | Идентификатор рабочей области команды; по умолчанию используется твоя личная рабочая область |
Если в рабочей области уже существует слаг dataset, в том числе в корзине, возвращается 409.
Допустимые значения task при создании или обновлении набора данных: detect, segment, semantic, depth, classify, pose и obb. У наборов данных глубины нет классов.
Ответ (201):
{
"id": "65f1c0a2b3d4e5f601234567",
"owner": "acme-vision",
"dataset": "warehouse",
"region": "us"
}Обновить набор данных#
PATCH /api/datasets/{owner}/{dataset}Python SDK: client.datasets.update(owner, dataset)
Тело запроса (частичное обновление):
{
"name": "Warehouse Safety",
"description": "New description",
"visibility": "public",
"metadata": { "location": "factory-2", "reviewed": true }
}Допустимые поля: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter, starred, blurFaces, kptSkeletonId (назначить шаблон скелета позы набору данных с позами) и initializeClassNames (обновление возвращает 409, если только в наборе данных еще нет классов или аннотаций). Чтобы очистить пользовательские метаданные, отправь пустой объект metadata ({}). Ключи метаданных могут содержать не более 128 символов, а сериализованный объект — не более 500 000 символов.
Ответ:
{
"success": true,
"dataset": "warehouse-safety"
}При переименовании меняется имя в URL, поэтому для последующих запросов используй возвращенное значение dataset.
Удаление набора данных#
DELETE /api/datasets/{owner}/{dataset}Python SDK: client.datasets.delete(owner, dataset)
Перемещает набор данных в корзину, откуда его можно восстановить в течение 30 дней.
Клонирование набора данных#
POST /api/datasets/{owner}/{dataset}/clonePython SDK: client.datasets.clone(owner, dataset)
Копирует доступный набор данных вместе с изображениями и метками в твоё личное или командное рабочее пространство. Необязательные splits (train, val, test) или imageIds клонируют только его часть (до 1 000 элементов), version клонирует сохранённую версию вместо актуальных изображений, annotations: false копирует изображения без меток, а into добавляет изображения без меток в принадлежащий тебе набор данных вместо создания нового. version нельзя использовать вместе с splits, imageIds, into или annotations: false.
Необязательное тело запроса (все поля необязательные):
{
"dataset": "warehouse-copy",
"name": "Warehouse Copy",
"description": "Cloned for experimentation",
"visibility": "private",
"license": "CC-BY-4.0",
"owner": "acme-vision"
}Ответ (201): id, owner, dataset, name, imageCount, classCount и region. Для наборов данных, подключённых к источнику хранилища, или наборов данных into, которые обрабатываются либо подключены, возвращается 409. Без visibility клон будет приватным, если для целевого рабочего пространства задана видимость по умолчанию Private, и в противном случае сохранит видимость источника.
Скачать экспорт набора данных#
GET /api/datasets/{owner}/{dataset}/exportPython SDK: client.datasets.export(owner, dataset)
Возвращает подписанный URL для скачивания NDJSON. Не указывай v, чтобы экспортировать текущее состояние набора данных; если с момента создания экспорта ничего не изменилось, будет использован кэшированный экспорт.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
v | целое число | Номер сохраненной версии (начиная с 1). Не указывай его, чтобы использовать текущую версию набора данных. |
Ответ:
{
"downloadUrl": "https://storage.googleapis.com/...&signature=...",
"cached": true
}При запросе конкретной версии возвращаются downloadUrl и version вместо cached.
Создать версию набора данных#
POST /api/datasets/{owner}/{dataset}/exportPython SDK: client.datasets.create_export(owner, dataset)
Создает неизменяемую версию набора данных с номером. Требуется доступ редактора. Установи download в false, чтобы сохранить версию без подготовки загрузки NDJSON; в таком случае downloadUrl не возвращается. SDK принимает download из ultralytics-platform>=0.1.73.
Тело запроса (необязательно):
{
"description": "Added 500 training images",
"download": true
}Ответ:
{
"version": 3,
"downloadUrl": "https://storage.googleapis.com/...&signature=...",
"reused": false
}Если набор данных совпадает с существующей версией, reused принимает значение true — например, сразу после восстановления. Вместо этого возвращается та версия; если ты передал описание, оно обновляется.
Обновить описание версии#
PATCH /api/datasets/{owner}/{dataset}/exportPython SDK: client.datasets.update_export(owner, dataset, version=..., description=...)
Тело запроса:
{
"version": 2,
"description": "Fixed mislabeled classes"
}Ответ: {"ok": true}
Восстановить версию набора данных#
POST /api/datasets/{owner}/{dataset}/restorePython SDK: client.datasets.restore(owner, dataset, version=...)
Восстанавливает изображения, аннотации и классы из сохраненной версии, не копируя байты изображений.
Тело запроса:
{
"version": 2
}Ответ: {"version": 2, "imageCount": 1000}
Сравнить версии набора данных#
GET /api/datasets/{owner}/{dataset}/versions/compare?base={from}&head={to}Python SDK: client.datasets.compare(owner, dataset, base=1, head=2) (ultralytics-platform>=0.1.73)
| Параметр | Тип | Описание |
|---|---|---|
base | int | Версия, с которой выполняется сравнение |
head | int | Версия, с которой сравнивается |
cursor | строка | nextCursor с предыдущей страницы |
hash | строка | hash элемента: вернуть это изображение в том виде, в каком оно хранится в каждой версии, а не изменения |
Ответ (сокращенный):
{
"summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
"items": [
{
"hash": "b5c605c133f84c3024af7e652b135501",
"name": "000000000042",
"change": "moved",
"base": { "split": "val", "labelCount": 1 },
"head": { "split": "test", "labelCount": 1 }
}
]
}summary появляется только на первой странице и содержит точные итоговые данные, а также header, в котором перечислены добавленные, удаленные или переименованные классы и другие отличающиеся поля набора данных. Для каждого элемента change имеет значение added, removed, modified (с измененным fields) или moved (изменен сплит), а labelsRemoved содержит метки удаленных изображений. Если присутствует nextCursor, передай его как cursor для получения следующей страницы. При использовании hash ответ содержит versions: изображение в том виде, в каком оно хранится в каждой версии, его метки и подписанный imageUrl. Порядок не имеет значения: если поменять местами base и head, удаленное изображение будет указано как добавленное. Для сравнений действует стандартный лимит частоты запросов; запросы без hash также ограничены 10 запросами в минуту для каждого пользователя и набора данных независимо от того, какой API-ключ используется.
Получить статистику набора данных#
GET /api/datasets/{owner}/{dataset}/class-statsPython SDK: client.datasets.class_stats(owner, dataset)
Возвращает количество аннотаций для каждого класса, гистограммы изображений и аннотаций, а также тепловые карты. Для больших наборов данных используется выборка; в этом случае sampleSize сообщает, сколько изображений было учтено.
Ответ (сокращённый):
{
"classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
"imageStats": {
"widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
"heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
"pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
"formatDistribution": { "jpg": 900, "png": 100 },
"fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
"objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
"bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
"bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
},
"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", "forklift"],
"cached": true,
"sampleSize": null
}Управление классами#
Объединить классы (переназначить аннотации целевому классу, затем удалить исходные классы):
POST /api/datasets/{owner}/{dataset}/classes/mergePython SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)
{
"sourceClassIds": [2, 4],
"targetClassId": 1
}Удалить классы (их аннотации будут удалены, а идентификаторы оставшихся классов сдвинутся вниз):
POST /api/datasets/{owner}/{dataset}/classes/deletePython SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)
{
"classIds": [2, 4]
}Обе операции возвращают success, обновлённые classNames и classColors, а также сводку изменений (mergedClassIds и targetClassId либо deletedClassIds и deletedAnnotations).
Поскольку после объединения или удаления идентификаторы оставшихся классов сдвигаются, эти операции не являются идемпотентными. Перед следующей операцией с классами заново запроси набор данных, чтобы получить актуальные индексы классов.
Перераспределить разбиения#
POST /api/datasets/{owner}/{dataset}/splits/redistributePython SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)
Случайным образом распределяет изображения по разбиениям. Сумма трёх процентов должна составлять 100.
{
"train": 80,
"val": 20,
"test": 0
}Ответ: success, получившееся количество элементов в splits и modified (число перемещённых изображений).
Эмбеддинги набора данных#
GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddingsPython SDK: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)
GET возвращает сводку анализа (analyzedAt, embeddingsCount, latestImageAt, activeJob). POST ставит анализ эмбеддингов в очередь и возвращает 202 с jobId либо 409, если для хранилища набора данных отключены функции ИИ или оно находится локально (On Premise). DELETE отменяет активное задание и возвращает идентификатор отменённого задания либо null.
Кластеризация изображений#
GET /api/datasets/{owner}/{dataset}/images/clusteringPython SDK: client.datasets.clustering(owner, dataset)
Возвращает двумерное представление UMAP по завершённому анализу с постраничной выдачей через offset и limit (по умолчанию и максимум — 50 000). Для каждой записи указаны id, umapX, umapY, cluster, split, classIds, width, height, bytes, labelCount, labeled и missing. cluster — это визуальный остров точки, ранжированный по размеру (0 = самый большой, -1 = рассеянный), либо null для представлений, проанализированных до появления кластеризации.
Список моделей, обученных на наборе данных#
GET /api/datasets/{owner}/{dataset}/modelsPython SDK: client.datasets.models(owner, dataset)
Ответ:
{
"models": [
{
"id": "65f1c0a2b3d4e5f601234599",
"owner": "acme-vision",
"project": "inspection",
"model": "v3",
"name": "v3",
"status": "completed",
"task": "detect",
"epochs": 100,
"bestEpoch": 87,
"metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
"startedAt": "2026-01-14T22:00:00Z",
"completedAt": "2026-01-15T10:00:00Z",
"createdAt": "2026-01-14T21:55:00Z"
}
],
"count": 1
}Список изображений набора данных#
GET /api/datasets/{owner}/{dataset}/imagesPython SDK: client.datasets.images(owner, dataset)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
limit | int | Максимальное количество возвращаемых изображений (по умолчанию: 50, максимум: 5000) |
offset | int | Количество пропускаемых изображений (по умолчанию: 0) |
cursor | строка | ID последнего изображения с предыдущей страницы для постраничной навигации с курсором |
includeTotal | логическое значение | Включить общее количество совпадений (по умолчанию: true) |
split | строка | Фильтр по разбиению: train, val, test |
hasLabel | логическое значение | Фильтр по состоянию аннотаций |
hasError | логическое значение | Фильтр по наличию ошибок обработки |
classIds | строка | ID классов, разделённые запятыми; возвращает изображения, содержащие хотя бы один из них |
search | строка | Поиск подстроки в имени файла, названии класса и пользовательских метаданных (не более 200 символов); запрос, заканчивающийся расширением файла изображения, например img_0042.jpg, выполняет поиск только по именам файлов |
q | строка | Сортирует по релевантности вместо sort: сначала совпадения по тексту, затем — до 1 000 похожих результатов; идентификатор, хеш или имя файла используется как search (максимум 200 символов) |
sort | строка | newest (по умолчанию), oldest, name-asc, name-desc, height-asc, height-desc, width-asc, width-desc, size-asc, size-desc, labels-asc, labels-desc |
includeThumbnails | логическое значение | Включить подписанные URL миниатюр (по умолчанию: true) |
includeImageUrls | логическое значение | Включить подписанные URL изображений в полном размере (по умолчанию: false) |
includeLabels | логическое значение | Включить ограниченный набор аннотаций для предварительного просмотра (по умолчанию: false) |
Ответ:
{
"images": [
{
"id": "65f1c0a2b3d4e5f601234567",
"hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
"ext": "jpg",
"name": "aisle-04",
"thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
"width": 1920,
"height": 1080,
"split": "train",
"labelCount": 6,
"bytes": 284213,
"error": null
}
],
"total": 1000,
"hasMore": true,
"classes": ["person", "forklift"],
"errorCount": 0,
"nextCursor": "65f1c0a2b3d4e5f601234567"
}Получить выбранные изображения#
POST /api/datasets/{owner}/{dataset}/imagesPython SDK: client.datasets.selected_images(owner, dataset, image_ids=...)
Возвращает изображения в том же формате для не более чем 1 000 переданных ID изображений и принимает те же параметры фильтрации и URL-запроса, что и операция получения списка.
{
"imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}Копирование или перемещение изображений#
POST /api/datasets/{owner}/{dataset}/images/adoptPython SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)
Копирует в этот набор данных до 1 000 изображений из других наборов данных, как это делает функция приложения копирования и вставки, и возвращает количество adopted.
{
"imageIds": ["65f1c0a2b3d4e5f601234567"],
"release": false,
"classMapping": { "person": 0, "vase": null }
}Указание release или classMapping сохраняет метки и разбиение на части для наборов данных, которые ты можешь редактировать: release: false копирует изображения, а release: true перемещает их из исходного набора данных. Если не указать ни одно из этих полей, импортируются изображения train без меток; то же происходит при копировании из источника только для чтения. При перемещении из источника только для чтения возвращается 403. Существующие изображения пропускаются; при сохранении меток и разбиения на части дубликаты проверяются в целевой части. Классы сопоставляются по названию без учета регистра для названий длиной более двух символов; 422 возвращает исходные классы, для которых нет совпадения в unmatchedClasses, а classMapping сопоставляет каждый класс с индексом класса, новым названием класса или null, чтобы удалить его метки. 409 означает, что целевой набор данных подключен либо исходный или целевой набор данных занят. При сохранении меток и разбиения на части несовместимость задач, каналов изображения, настроек позы или шкал глубины также приводит к 409, даже для изображений без меток.
Импорт данных в набор данных#
POST /api/datasets/{owner}/{dataset}/ingestPython SDK: client.datasets.ingest(owner, dataset, body=...)
Импортирует данные в существующий набор данных из завершённой загрузки, удалённого архива или подключённого источника хранения. Укажи ровно один источник:
| Поле | Тип | Описание |
|---|---|---|
sessionId | строка | Сеанс загрузки из POST /api/upload/signed-url; импорт проверяет и завершает загрузку, если вызов POST /api/upload/complete ещё не выполнялся |
sourceUrl | строка | Общедоступный HTTP- или HTTPS-URL файла ZIP, TAR, TAR.GZ, TGZ или NDJSON (максимум 4096 символов) |
reference | объект | Подключённый источник: облачное хранилище (provider: "cloud", integrationId, target, prefix) или локальное хранилище (On Premise) (provider: "local", keyId, root, prefix) |
targetSplit | строка | train, val или test; переопределяет структуру разбиений архива |
conflictPolicy | строка | skip, keep_both или replace при конфликтах имён файлов или содержимого |
classMapping | объект | Сопоставляет входящие имена классов с индексом класса, существующим или новым именем класса либо с null, чтобы пропустить класс |
imageMetadata | объект | Пользовательские метаданные, ключом которых служит путь каждого изображения относительно архива или значение NDJSON file |
Сеансы загрузки привязаны к набору данных через assetId, переданный в POST /api/upload/signed-url; импорт отклоняет сеанс, связанный с другим набором данных.
Тело запроса (загруженный архив):
{
"sessionId": "session_abc123",
"targetSplit": "train"
}Тело запроса (удалённый архив или NDJSON):
{
"sourceUrl": "https://example.com/my-dataset.zip"
}Тело запроса (импорт меток при последующем импорте):
{
"sessionId": "session_abc123",
"classMapping": { "person": 0, "automobile": "forklift", "background": null }
}Тело запроса (добавление метаданных для каждого изображения):
{
"sessionId": "session_abc123",
"imageMetadata": {
"airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
"images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
}
}Ключи метаданных должны совпадать с нормализованным путём внутри архива, включая папки. При импорте NDJSON каждая запись может содержать собственный объект metadata, который имеет приоритет над соответствующей записью imageMetadata. Длина путей в архиве ограничена 1 024 символами, ключей метаданных верхнего уровня — 128 символами, а каждого объекта метаданных и всей карты imageMetadata — 500 000 сериализованных символов.
При первом импорте классы автоматически создаются из архива. При последующих импортах классы архива, не указанные в classMapping, сопоставляются по названию с существующими классами набора данных без учета регистра для названий длиной более двух символов; классы без совпадений добавляются как новые. Метки пропускаются только для классов, явно сопоставленных с null.
Ответ (201):
{
"jobId": "65f1c0a2b3d4e5f6012345aa",
"status": "queued"
}Загрузка одного изображения с метаданными с помощью Python
Этот же код работает с группой изображений: добавь в ZIP другие файлы и соответствующие записи в imageMetadata.
import io
import zipfile
from pathlib import Path
import requests
api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567" # id returned by POST /api/datasets
image_path = Path("airbus-wing.jpg")
archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
zf.write(image_path, image_path.name)
data = archive.getvalue()
signed = requests.post(
f"{api}/upload/signed-url",
headers=headers,
json={
"assetType": "datasets",
"assetId": dataset_id,
"filename": "images.zip",
"contentType": "application/zip",
"totalBytes": len(data),
},
)
signed.raise_for_status()
upload = signed.json()
headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, data=data).raise_for_status()
requests.post(
f"{api}/upload/complete",
headers=headers,
json={"sessionId": upload["sessionId"]},
).raise_for_status()
ingest = requests.post(
f"{api}/datasets/{owner}/{dataset}/ingest",
headers=headers,
json={
"sessionId": upload["sessionId"],
"imageMetadata": {
"airbus-wing.jpg": {
"aircraft": {"family": "A350", "section": "wing"},
"inspectionStatus": "reviewed",
}
},
},
)
ingest.raise_for_status()
print(ingest.json())API изображений#
Просматривай, аннотируй, перемещай и удаляй изображения набора данных по их 24-символьному ID. См. документацию по аннотациям.
Получить изображение#
GET /api/images/{imageId}Python SDK: client.images.retrieve(image_id)
Возвращает объект metadata (пользовательские данные), properties (имя файла, хеш, размеры, разбиение, количество объектов, временные метки), labels и classNames набора данных.
Обновить изображение#
PATCH /api/images/{imageId}Python SDK: client.images.update(image_id, body=...)
Заменяет либо аннотации, либо пользовательские метаданные — отправь одну из двух структур, но не обе.
Тело запроса (аннотации):
{
"labels": [
{ "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
{ "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
]
}Тело запроса (метаданные):
{
"metadata": { "location": "strasbourg", "reviewed": true }
}Координаты меток задаются нормализованными значениями YOLO от 0 до 1. Для ограничивающих рамок используется [x_center, y_center, width, height]. Для сегментационных меток используется segments — уплощённый список вершин полигона [x1, y1, x2, y2, ...]. Для меток поз используется keypoints в едином плоском формате: пары [x1, y1, x2, y2, ...] или тройки [x1, y1, v1, x2, y2, v2, ...], где видимость обычно принимает значения 0, 1 или 2. Для ориентированных рамок используются углы obb. Сохранённые координаты округляются до 5 знаков после запятой; для одного изображения допускается не более 10 000 аннотаций.
Удалить изображение#
DELETE /api/images/{imageId}Python SDK: client.images.delete(image_id)
Безвозвратно удаляет одно изображение и его аннотации.
Автоматически аннотировать изображение#
POST /api/images/{imageId}/predictPython SDK: client.images.predict(image_id, model_id=...)
Запускает модель на изображении и возвращает предсказанные аннотации. Они не сохраняются — запиши результаты обратно с помощью PATCH /api/images/{imageId}, когда они тебя устроят.
| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
modelId | строка | Да | Полный URI модели, ul://{owner}/{project}/{model} или ID модели с подсказками классов для набора данных обнаружения с 1–200 классами (yoloe26x вместе с visualPrompts также поддерживает наборы данных сегментации и OBB): размещённая модель (qwen, gemma, nemotron, moondream, wevisone, florence2, owlv2, yoloe26x, sam3, sam3.1, groundingdino) или ID платной модели провайдера из перечисления modelId в openapi.json |
confidence | float | Нет | Порог уверенности, 0.01–1.0 (по умолчанию: 0.25); игнорируется моделями с подсказками классов без visualPrompts, в которых используются пороги, заданные для конкретной модели |
iou | float | Нет | Порог IoU для подавления немаксимумов, 0.0 – 0.95 (по умолчанию: 0.5); игнорируется моделями с подсказками классов без visualPrompts |
visualPrompts | массив | Нет | На датасете для детекции, сегментации или OBB с modelId yoloe26x — от 1 до 200 объектов разметки (classId плюс bbox, segments или obb) с этого изображения либо с изображения referenceImageId; модель повторно находит их классы на изображении |
referenceImageId | строка | Нет | С visualPrompts — идентификатор изображения из того же датасета, на котором нарисованы подсказки, если это не изображение, для которого выполняется предсказание |
classMapping | массив | Нет | Для модели YOLO — индекс класса датасета для каждого класса модели в заданном порядке либо null, чтобы исключить этот класс; если длина списка неверна или индекс выходит за пределы классов датасета, возвращается 400. Игнорируется моделями с подсказками классов и не допускается с visualPrompts |
Ответ: success, predictions (объекты аннотаций), confidences (оценки, выровненные по индексам; пусто для моделей с подсказками классов без visualPrompts), modelUsed, inferenceTime, usage ([input tokens, output tokens], если языковая модель их возвращает); для моделей с подсказками классов — partial (true, если ограничение по времени или количеству выходных данных привело к преждевременному завершению ответа либо есть подозрение на это, поэтому в возвращённых аннотациях могут отсутствовать объекты); для платных моделей провайдеров — необязательное поле cost (предполагаемая стоимость услуг провайдера в долларах США, списываемая с ключа провайдера; отсутствует, если оценка недоступна). Модель YOLO с классами, не совпадающими с датасетом, возвращает 422. Тот же код возвращает модель с подсказками классов, если датасет не предназначен для обнаружения, содержит не от 1 до 200 классов (кроме случая, когда используется visualPrompts), используется visualPrompts с другой моделью или задачей, задан неизвестный classId, подсказка слишком мала или находится за пределами изображения либо задан classMapping. Платная модель провайдера без сохранённого ключа провайдера в разделе Настройки > Ключи API рабочего пространства датасета возвращает code: missing_provider_api_key. Если referenceImageId не является изображением в этом датасете, возвращается 404. Ошибка провайдера содержит его сообщение: 422, если провайдер возвращает 400, 401, 402, 403 или 404 (отклонённый ключ, модель или запрос либо неоплаченный баланс провайдера; code: provider_refused для всех случаев, кроме 400); 429 при превышении лимита запросов; 503 при любой другой ошибке провайдера. Для датасетов глубины возвращается 400. Для датасетов On Premise, датасетов в облачном хранилище с отключёнными функциями ИИ или отключёнными учётными данными, а также датасетов с более чем 3 каналами изображения возвращается 409.
Поиск похожих изображений#
GET /api/images/{imageId}/similarPython SDK: client.images.find_similar_images(image_id)
Возвращает до 24 визуально похожих images из общедоступных датасетов, а также из твоих и командных датасетов. Для каждого результата указаны score (0–1), знаковое значение thumbnailUrl и исходный dataset (owner, dataset, license). Исходный датасет и датасеты с копией изображения, по которому выполняется поиск, исключаются; параметр includeSourceDataset=true оставляет их в результатах и исключает только копии. Параметры license (идентификаторы через запятую из раздела Доступные лицензии, с None для датасетов без лицензии) и publicOnly=true (только общедоступные датасеты) сужают поиск, который по-прежнему возвращает до 24 изображений. Требуется API-ключ с правом просмотра изображения; если для изображения ещё не создан эмбеддинг, он создаётся сначала. Значение 503 означает, что подготовка не удалась; повтори попытку. Собственный датасет изображения из облачного хранилища включается в поиск только в его рабочем пространстве. Значение 409 означает, что для хранилища изображения отключены функции ИИ или датасет размещён на On Premise.
Автоматически аннотировать набор данных#
POST /api/datasets/{owner}/{dataset}/predict/batchPython SDK: client.datasets.create_batch(owner, dataset, body={...}) (ultralytics-platform>=0.1.57)
Сохраняет версию датасета (у датасетов в облачном хранилище версий нет), затем ставит в очередь запуск, который размечает моделью неразмеченные изображения датасета, и возвращает 202. Тело запроса принимает те же поля modelId, confidence, iou и classMapping, что и конечная точка для одного изображения, а также includeAnnotated (по умолчанию false), чтобы размечать и изображения с уже имеющимися метками. С modelId yoloe26x, visualPrompts и referenceImageId (обязательно указывать вместе с ними; 422, если его нет; 404, если этого изображения больше нет в датасете) запускает поиск похожих на примеры объектов на изображениях запуска (только неразмеченных, если не задано includeAnnotated) на датасетах для детекции, сегментации и OBB; примеры кодируются один раз при запуске. Модель с подсказками классов обнаруживает классы датасета без оценок уверенности, а для платной модели провайдера нужен ключ провайдера, сохранённый в рабочем пространстве датасета в разделе Настройки > Ключи API (422, code: missing_provider_api_key, до постановки запуска в очередь). Существующие метки не изменяются; предсказания, перекрывающие существующую метку того же класса больше, чем на iou, пропускаются; оплата взимается за фактически обработанные изображения. 402 означает, что баланса не хватает для покрытия расчётной стоимости; 409 — что датасет не готов, в его хранилище отключены функции ИИ или оно является хранилищем On Premise, не осталось изображений для разметки либо уже выполняется запуск; 422 означает, что у датасета нет классов или для модели с подсказками классов выбрали датасет не для детекции либо датасет с числом классов вне диапазона 1–200. Прежде чем вызывать эту конечную точку, создай классы через конечную точку классов — именно этот шаг Map classes приложение выполняет перед запуском.
GET по тому же пути (client.datasets.batch(owner, dataset)) возвращает выполняющийся запуск и его прогресс либо последний завершённый запуск до его закрытия; в его results включён partialImages, если при запуске генеративной модели из усечённого вывода оставлены только полные рамки. DELETE (client.datasets.delete_batch(owner, dataset)) отменяет выполняющийся запуск либо завершает расчёты и закрывает сводку завершённого запуска.
Тот же endpoint размывает лица с помощью "operation": "blur", confidence (по умолчанию 0.25) и boxScale (0.5–1.5, по умолчанию 1); imageId ограничивает запуск одним изображением. Версия не создаётся, а метки не изменяются. Отправь "preview": true, чтобы обработать до шести изображений без внесения изменений, а затем передай возвращённый jobId как previewJobId с теми же настройками, чтобы применить результат; повторно использовать применённый предварительный просмотр нельзя — возвращается 409. Пока предварительный просмотр ожидает применения, передай его ID в DELETE как previewJobId, чтобы удалить его.
{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }Массовое перемещение изображений#
PATCH /api/images/bulkPython SDK: client.images.update_bulk(image_ids=..., split=...)
Перемещает до 1 000 изображений из одного набора данных в другое разбиение.
{
"imageIds": ["65f1c0a2b3d4e5f601234567"],
"split": "val",
"conflictPolicy": "skip"
}При конфликте имён файлов или содержимого возвращается 409, пока ты не выберешь единый для всей группы параметр conflictPolicy: skip, keep_both или replace. В ответе указаны modifiedCount, skippedCount и targetSplit.
Массовое удаление изображений#
DELETE /api/images/bulkPython SDK: client.images.delete_bulk(image_ids=...)
{
"imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}Удаляет до 1 000 изображений из одного набора данных и возвращает deletedCount и deletedImageIds.
Получить подписанные URL изображений#
POST /api/images/urlsPython SDK: client.images.urls(image_ids=...)
Возвращает временные подписанные URL для не более чем 100 ID изображений из одного набора данных.
{
"imageIds": ["65f1c0a2b3d4e5f601234567"]
}Ответ: urls, thumbnails и depths (предварительные просмотры целевых данных глубины для парных изображений глубины); все значения сгруппированы по ID изображения.
API проектов#
Упорядочивай модели по проектам. Каждая модель относится к одному проекту. См. документацию по проектам.
Список проектов#
GET /api/projects/{owner}Python SDK: client.projects.list(owner)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
limit | int | Максимальное количество возвращаемых проектов (по умолчанию: 20, максимум: 500) |
Получить проект#
GET /api/projects/{owner}/{project}Python SDK: client.projects.retrieve(owner, project)
Возвращает объект project, массив models со сводками по каждой модели (статус, метрики, эпохи, веса, аргументы обучения) и isOwner. Передай search (максимум 200 символов), чтобы отфильтровать models по имени модели или метаданным.
Создание проекта#
POST /api/projectsPython SDK: client.projects.create(project=..., name=...)
| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
project | строка | Да | Имя проекта, используемое в URL Platform |
name | строка | Да | Отображаемое имя (не более 100 символов) |
description | строка | Нет | Описание (не более 1000 символов) |
visibility | строка | Нет | public или private (по умолчанию: видимость по умолчанию рабочего пространства) |
tags | массив | Нет | До 50 тегов |
license | строка | Нет | Идентификатор лицензии проекта |
metadata | объект | Нет | Пользовательские метаданные JSON |
owner | строка | Нет | Идентификатор рабочей области команды; по умолчанию используется твоя личная рабочая область |
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "inspection",
"name": "Inspection",
"description": "Detection experiments",
"metadata": {"department": "manufacturing", "cost_center": "cv-01"}
}' \
https://platform.ultralytics.com/api/projectsОтвет (201): id, owner, project, region.
Если в рабочей области уже существует слаг project, в том числе в корзине, возвращается 409.
Обновить проект#
PATCH /api/projects/{owner}/{project}Python SDK: client.projects.update(owner, project)
Допустимые поля: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences и starred.
{
"metadata": { "department": "research", "program": "inspection" }
}Отправь пустой объект metadata ({}), чтобы очистить его. Для метаданных проекта действуют те же ограничения, что и для метаданных датасета: ключ не длиннее 128 символов и сериализованный объект не больше 500 000 символов. Изменение name, меняющее slug, возвращает 409, пока любая модель проекта начинает обучение.
Удаление проекта#
DELETE /api/projects/{owner}/{project}Python SDK: client.projects.delete(owner, project)
Перемещает проект и его модели в корзину, возвращая cascadedModels, и безвозвратно удаляет их развертывания. Восстановление проекта не восстанавливает развертывания. 502 означает, что очистка развертываний не завершилась; модели останутся в корзине, пока она не завершится.
Клонирование проекта#
POST /api/projects/{owner}/{project}/clonePython SDK: client.projects.clone(owner, project)
Клонирует доступный проект и его завершённые модели. В необязательном теле запроса можно указать project, name, description, visibility, license, целевую owner и models — список названий моделей для клонирования вместо всех завершённых моделей. Если параметр visibility не указан, клон будет приватным, когда для целевой рабочей области задана видимость по умолчанию Private; в противном случае он сохранит видимость исходного проекта. Если модели клона превысят лимит моделей целевой рабочей области, запрос вернёт 403 и ничего не скопирует.
API моделей#
Управляй обученными моделями YOLO: просматривай метрики, скачивай веса, запускай инференс и следи за обучением. Подробнее см. в документации по моделям.
Список моделей проекта#
GET /api/models/{owner}/{project}Python SDK: client.models.list(owner, project)
В списке моделей не отображаются данные валидации plots и trainResults; действие Получить модель возвращает их.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
limit | int | Максимальное число возвращаемых моделей (по умолчанию: 20, максимум: 100) |
Получить модель#
GET /api/models/{owner}/{project}/{model}Python SDK: client.models.retrieve(owner, project, model)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
analysis | int | Задай значение 1, чтобы получить анализ валидации по каждому изображению вместо модели |
Ответ по умолчанию содержит объект model — статус, задачу, метрики, trainArgs, trainResults, classNames, computeCost, metadata и другие поля, — а также isOwner.
Создать модель#
POST /api/modelsPython SDK: client.models.create(body=...)
Создает запись необученной модели, к которой можно прикрепить веса или которую можно обучить.
| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
project | строка | Да | Название целевого проекта |
owner | строка | Нет | Идентификатор рабочего пространства; по умолчанию используется твое личное рабочее пространство |
model | строка | Нет | Название модели, используемое в URL-адресах Platform; создается автоматически, если не указано |
name | строка | Нет | Отображаемое имя (принимается только вместе с model) |
description | строка | Нет | Описание (не более 1000 символов) |
task | строка | Нет | detect, segment, semantic, depth, classify, pose или obb |
metadata | объект | Нет | Пользовательские метаданные JSON |
trainArgs | объект | Нет | Аргументы обучения для сохранения |
metrics | объект | Нет | Метрики, например mAP50, mAP50-95, precision, recall |
epochs | число | Нет | Количество эпох для уже обученной модели |
version | строка | Нет | Метка версии (не более 50 символов) |
Ответ (201): id, owner, project, model, name, region. Ответ содержит slug модели и отображаемое имя, выбранное после разрешения конфликтов имён.
Чтобы прикрепить веса .pt, запроси подписанный URL для загрузки с помощью assetType: "models" и передай id этой модели как assetId, загрузи файл по возвращенному URL с помощью PUT, затем вызови POST /api/upload/complete, передав возвращенный sessionId.
Обновить модель#
PATCH /api/models/{owner}/{project}/{model}Python SDK: client.models.update(owner, project, model)
К допустимым полям относятся name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError и starred. Передача только projectId перемещает модель в другой проект того же владельца; ответ содержит slug модели в целевом проекте, renamed: true, если этот slug там уже занят, и 409, пока модель ещё обучается. Изменение name, меняющее slug, возвращает 409, пока начинается обучение.
{
"metadata": { "release": "candidate-3", "reviewed": true }
}Пользовательское поле metadata отделено от полей, которыми управляет обучение, например trainArgs, environment и trainResults; для него действуют те же ограничения размера, что и для метаданных набора данных.
Удалить модель#
DELETE /api/models/{owner}/{project}/{model}Python SDK: client.models.delete(owner, project, model)
Перемещает модель в корзину на 30 дней и безвозвратно удаляет все использующие ее развертывания, включая ожидающие замены. Восстановление модели не восстанавливает развертывания.
Скачать файлы модели#
GET /api/models/{owner}/{project}/{model}/filesPython SDK: client.models.files(owner, project, model)
Возвращает краткосрочные подписанные URL-адреса весов модели, названных в честь модели ({model}.pt).
{
"files": [
{
"name": "my-model.pt",
"size": 6534127,
"downloadUrl": "https://storage.googleapis.com/...&signature=..."
}
]
}Найти изображения, похожие на изображения с худшими результатами валидации#
GET /api/models/{owner}/{project}/{model}/similar-imagesPython SDK: client.models.find_similar_training_images(owner, project, model)
Возвращает до 100 images в том же формате, что и Поиск похожих изображений, которые похожи на изображения валидации с самыми низкими оценками в этом запуске обучения. Изображения, уже имеющиеся в обучающем датасете запуска, исключаются. Передай hashes (до 100 значений через запятую), чтобы выполнить поиск по части этих изображений с наихудшими результатами, а также license или publicOnly, чтобы сузить поиск, как в Поиске похожих изображений. Требуется API-ключ с доступом к рабочему пространству модели. Список будет пустым, если для запуска не были записаны результаты по каждому изображению; значение 404 также означает, что для изображений с наихудшими результатами ещё не созданы эмбеддинги: сначала запусти создание эмбеддингов датасета для обучающего датасета.
Клонирование модели#
POST /api/models/{owner}/{project}/{model}/clonePython SDK: client.models.clone(owner, project, model, project_body=...)
Копирует доступную модель в существующий проект.
{
"owner": "acme-vision",
"project": "inspection",
"model": "v3-copy",
"name": "V3 Copy",
"description": "Cloned from a public model"
}| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
project | строка | Да | Название целевого проекта |
owner | строка | Нет | Целевое рабочее пространство; по умолчанию используется твое личное |
model | строка | Нет | Название целевой модели |
name | строка | Нет | Отображаемое имя целевой модели |
description | строка | Нет | Описание копии |
Запусти инференс#
POST /api/models/{owner}/{project}/{model}/predictPython SDK: client.models.predict(owner, project, model, body=...)
Для предсказаний по публичным моделям аутентификация не нужна. Для приватных моделей и моделей с общим доступом требуется API-ключ с доступом к родительскому проекту.
Составная форма:
| Параметр | Тип | По умолчанию | Диапазон | Описание |
|---|---|---|---|---|
file | файл | - | - | Файл изображения или видео (обязателен, если не задан source) |
conf | float | 0.25 | 0.01 – 1.0 | Минимальный порог уверенности |
iou | float | 0.5 | 0.0 – 0.95 | Порог IoU для NMS |
imgsz | int | - | 32 – 1280 | Размер входного изображения в пикселях; по умолчанию используется размер при обучении модели (640, если он недоступен) |
normalize | bool | false | - | Возвращать координаты рамок в диапазоне от 0 до 1 |
decimals | int | 5 | 0 – 10 | Точность десятичного представления координат |
vid_stride | int | 1 | ≥ 1 | Обрабатывать каждый N-й кадр видео; для изображений параметр игнорируется |
bits | int | 8 | 8, 12, 16 | Квантование карты глубины; только для моделей оценки глубины |
source | строка | - | - | URL изображения или строка в формате base64 (альтернатива file); максимум 4 096 символов при использовании API платформы |
Укажи либо file, либо source. Для моделей глубины также можно передать bits (8, 12 или 16), чтобы выбрать квантование PNG-карты глубины. Если запрос превышает ограничения сервиса на входные данные, возвращается 413.
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@image.jpg" \
-F "conf=0.5" \
https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/predictОтвет:
Каждая запись в images содержит shape, speed, results (до 1 000 на изображение, 300 для моделей RT-DETR), а для задач плотного предсказания — PNG-данные semantic_mask или depth (значения глубины представлены как pixel × max / divisor; делитель равен 255 для карты по умолчанию с глубиной 8 бит и 65535, если bits равно 12 или 16). Объект metadata содержит количество изображений, время выполнения функций, задачу и версии сервисов. Внутренние пути к моделям не возвращаются.
{
"images": [
{
"shape": [1080, 1920],
"speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
}
]
}
],
"metadata": {
"imageCount": 1,
"functionTimeAlive": 184.2,
"functionTimeCall": 0.31,
"task": "detect",
"version": { "ultralytics": "8.4.120" }
}
}Проверить ход обучения#
GET /api/models/{owner}/{project}/{model}/trainingPython SDK: client.models.training(owner, project, model)
Возвращает job с данными о статусе, ходе эпох, времени, вычислительных ресурсах, аргументах обучения, метриках эпох и безопасными сведениями об ошибках либо null, если модель еще ни разу не обучалась. Данные о моделях в публичных проектах доступны без аутентификации.
Отмена обучения#
DELETE /api/models/{owner}/{project}/{model}/trainingPython SDK: client.models.delete_training(owner, project, model)
Останавливает работающий вычислительный экземпляр и отмечает задание как отмененное. Возвращает 409, если обучение уже не выполняется.
API обучения#
Запускай обучение YOLO на облачных GPU и следи за ходом обучения в реальном времени. Подробнее см. в документации по облачному обучению.
Получить доступность GPU#
GET /api/training/gpu-availabilityPython SDK: client.training.gpu_availability()
Возвращает текущий статус наличия ресурсов с привязкой к ID GPU. Доступно всем без аутентификации; передай managed=true, чтобы включить мощности управляемого обучения — для этого потребуется API-ключ.
Начать обучение#
POST /api/training/startPython SDK: client.training.start(model_id=..., train_args=...)
| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
modelId | строка | Да | ID модели для обучения |
trainArgs | объект | Да | Аргументы обучения YOLO; требуются model, data и epochs. data — это URI набора данных ul://username/datasets/slug или YAML-файл встроенного набора данных, например coco8.yaml |
gpuType | строка | Нет | Облачный GPU для использования (по умолчанию: rtx-4090) |
captureDatasetVersion | логическое значение | Нет | Сохранить неизменяемую версию набора данных для этого запуска (по умолчанию: false) |
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"modelId": "65f1c0a2b3d4e5f601234599",
"gpuType": "rtx-4090",
"trainArgs": {
"model": "yolo26n.pt",
"data": "ul://acme-vision/datasets/warehouse",
"epochs": 100,
"imgsz": 640,
"batch": 16
}
}' \
https://platform.ultralytics.com/api/training/startОтвет:
{
"modelId": "65f1c0a2b3d4e5f601234599",
"status": "starting",
"gpuType": "rtx-4090",
"estimatedCost": { "pricePerHour": 0.89, "gpuMemoryGb": 24 },
"billing": {
"estimatedCostCents": 178,
"estimatedCostDisplay": "$1.78",
"balanceCents": 2500
}
}Обучение возвращает 400, если data — это идентификатор набора данных или путь к набору данных Platform без ul://, либо если задача модели не поддерживает обучение на задаче набора данных; 402 — если на балансе недостаточно средств; 409 — если функции ИИ отключены для облачного хранилища набора данных или оно отключено; 503 — если нет свободных ресурсов для запрошенного GPU.
Доступно 26 типов GPU: от rtx-2000-ada до b300, включая rtx-4090, l40s, a100-80gb-pcie, a100-80gb-sxm, rtx-pro-6000, h100-sxm, h200-sxm и b200. Полный список смотри в разделе Облачное обучение.
API экспорта#
Преобразуй модели в оптимизированные форматы, например ONNX, TensorRT, CoreML и LiteRT, для развертывания на периферийных устройствах.
Список экспортов#
GET /api/models/{owner}/{project}/{model}/exportsPython SDK: client.exports.list(owner, project, model)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
status | строка | Фильтр по queued, starting, running, completed, failed или cancelled |
limit | int | Максимальное число возвращаемых экспортов (по умолчанию: 20, максимум: 100) |
Создать экспорт#
POST /api/models/{owner}/{project}/{model}/exportsPython SDK: client.exports.create(owner, project, model, format=...)
| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
format | строка | Да | Целевой формат экспорта (см. таблицу ниже) |
gpuType | строка | Условно обязательное | Обязательно, если format равно engine; укажи поддерживаемую цель GPU или Jetson |
args | объект | Нет | Параметры экспорта: imgsz, quantize, dynamic, simplify, opset, conf, iou, batch, workspace, nms, optimize и name (целевое устройство для RKNN, QNN, Hailo, Ascend и Xilinx) |
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exportsКаждый формат поддерживает только параметры из столбца Аргументы в таблице экспорта ниже: если для формата указать отличающееся от значения по умолчанию значение batch, dynamic, opset, simplify, workspace или optimize, который не поддерживается этим форматом, вернется 400. Экспорт imx доступен только в формате INT8 для моделей обнаружения объектов, сегментации, классификации и определения позы; для модели, название которой указывает на YOLO, отличную от YOLOv8n или YOLO11n, вернется 400.
Ответ (201): id, format, status (queued или running), region и gpuType для экспортов TensorRT. Пока выполняется экспорт модели в том же формате, новый запрос возвращает 409 независимо от значения args.
Поддерживаемые форматы:
Используй аргумент format из общей таблицы экспорта ниже. PyTorch — исходный формат, а не целевой формат экспорта через API.
| Формат | Аргумент format | Модель | Метаданные | Аргументы |
|---|---|---|---|---|
| PyTorch | - | yolo26n.pt | ✅ | - |
| TorchScript | torchscript | yolo26n.torchscript | ✅ | imgsz, quantize, dynamic, nms, batch, device |
| ONNX | onnx | yolo26n.onnx | ✅ | imgsz, quantize, dynamic, simplify, opset, nms, batch, data, fraction, device |
| OpenVINO | openvino | yolo26n_openvino_model/ | ✅ | imgsz, quantize, dynamic, nms, batch, data, fraction, device |
| TensorRT | engine | yolo26n.engine | ✅ | imgsz, quantize, dynamic, simplify, opset, workspace, nms, batch, data, fraction, device |
| CoreML | coreml | yolo26n.mlpackage | ✅ | imgsz, dynamic, quantize, nms, batch, device |
| Apple Core AI | coreai | yolo26n.aimodel | ✅ | imgsz, batch, quantize |
| TF SavedModel | saved_model | yolo26n_saved_model/ | ✅ | imgsz, quantize, opset, nms, batch, data, fraction, device |
| TF GraphDef | pb | yolo26n.pb | ❌ | imgsz, opset, batch, device |
| TF Edge TPU | edgetpu | yolo26n_edgetpu.tflite | ✅ | imgsz, quantize, opset, data, fraction, device |
| LiteRT | litert | yolo26n.tflite | ✅ | imgsz, quantize, batch, data, fraction, device |
| PaddlePaddle | paddle | yolo26n_paddle_model/ | ✅ | imgsz, batch, device |
| MNN | mnn | yolo26n.mnn | ✅ | imgsz, batch, dynamic, quantize, simplify, opset, nms, device |
| NCNN | ncnn | yolo26n_ncnn_model/ | ✅ | imgsz, quantize, device |
| IMX500 | imx | yolo11n_imx_model/ | ✅ | imgsz, quantize, data, fraction, nms, device |
| RKNN | rknn | yolo26n_rknn_model/ | ✅ | imgsz, batch, name, quantize, simplify, opset, data, fraction, device |
| ExecuTorch | executorch | yolo26n_executorch_model/ | ✅ | imgsz, quantize, batch, data, fraction, device |
| Axelera | axelera | yolo26n_axelera_model/ | ✅ | imgsz, batch, quantize, data, fraction, device |
| DEEPX | deepx | yolo26n_deepx_model/ | ✅ | imgsz, quantize, simplify, opset, data, optimize, device |
| Qualcomm QNN | qnn | yolo26n_qnn.onnx | ✅ | imgsz, batch, name, quantize, simplify, opset, data, fraction, device |
| Hailo | hailo | yolo26n_hailo_model/ | ✅ | imgsz, name, quantize, data, fraction, simplify, conf, iou, device |
| Huawei Ascend | ascend | yolo26n_ascend_model/ | ✅ | imgsz, batch, name, quantize, opset, simplify, nms, device |
| AMD Xilinx | xilinx | yolo26n_xilinx_model/ | ✅ | imgsz, name, quantize, data, fraction, opset, simplify, device |
| NXP | nxp | yolo26n_nxp.tflite | ✅ | imgsz, quantize, data, fraction, device |
nms=None по умолчанию выдаёт необработанные выходные данные для внешней NMS (YOLO26 сохраняет голову без NMS на Axelera). Укажи nms=False, чтобы выбрать доступную голову без NMS; неподдерживаемые форматы используют собственный путь вывода. Записи nms выше указывают форматы, в которые можно встроить NMS с помощью nms=True.
Получить статус экспорта#
GET /api/models/{owner}/{project}/{model}/exports/{exportId}Python SDK: client.exports.retrieve(owner, project, model, export_id)
Возвращает объект export с полями status, format, args, gpuType (только для TensorRT), временными метками и, после завершения, объектом file, содержащим size, downloadUrl и downloadFilename.
Создать ссылку для мобильного импорта#
POST /api/models/{owner}/{project}/{model}/exports/{exportId}/mobilePython SDK: пока нет; отправь HTTP-запрос напрямую.
Возвращает importUrl и expiresAt, чтобы открыть завершённый экспорт CoreML, Core AI или LiteRT в приложении Ultralytics YOLO. Срок действия ссылки истекает через 24 часа, и до этого момента любой, у кого есть ссылка, может скачать экспорт. Для незавершённого или несовместимого экспорта возвращается 409.
Отменить или удалить экспорт#
DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}Python SDK: client.exports.delete(owner, project, model, export_id)
Отменяет выполняющийся экспорт или удаляет завершенный экспорт и его файл. В ответе указывается, какое действие выполнено:
{
"success": true,
"action": "cancelled"
}API развертываний#
Развертывай модели на выделенных конечных точках инференса с проверками работоспособности и мониторингом. Подробнее см. в документации по конечным точкам.
Список развертываний#
GET /api/deployments/{owner}Python SDK: client.deployments.list(owner)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
status | строка | creating, deploying, ready, stopping, stopped или failed |
model | строка | Фильтр по {project}/{model}, например inspection/v3 |
limit | int | Максимальное число возвращаемых развертываний (по умолчанию: 20, максимум: 100) |
Анонимные пользователи должны фильтровать результаты по одной публичной модели; чтобы получить список для всего рабочего пространства, требуется аутентификация.
Создать развертывание#
POST /api/deployments/{owner}Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)
Тело запроса:
{
"project": "inspection",
"model": "v3",
"deployment": "edge-1",
"name": "Edge 1",
"region": "us-central1"
}| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
project | строка | Да | Проект, содержащий модель |
model | строка | Да | Модель для развертывания |
deployment | строка | Да | Название развертывания, используемое в URL-адресах Platform |
name | строка | Да | Отображаемое имя |
region | строка | Да | Один из 42 поддерживаемых регионов развертывания |
cpu | число | Нет | Ядра vCPU: 1 (по умолчанию), 2, 4, 6 или 8 |
memoryGi | число | Нет | Память в ГиБ: 2 (по умолчанию), 4, 8, 16, 24 или 32 |
Ответ (201): id, deployment, status (creating), message и region.
Конфигурация по умолчанию — 1 vCPU / 2 ГиБ — при простое масштабируется до нуля; для нее может действовать бесплатный лимит развертываний. Для остальных конфигураций применяется оплата по факту использования. Текущие значения возвращаются в объекте resources при каждом получении данных о развертывании.
Выбери регион рядом с пользователями, чтобы минимизировать задержку. В интерфейсе Platform отображаются оценки задержки для всех 42 доступных регионов.
Получить развертывание#
GET /api/deployments/{owner}/{deployment}Python SDK: client.deployments.retrieve(owner, deployment)
Возвращает объект deployment с status, statusMessage, region, serviceUrl, resources и пользовательским metadata, а также camera и cameraApplying для владельца.
Обновить развертывание#
PATCH /api/deployments/{owner}/{deployment}Python SDK: client.deployments.update(owner, deployment, body=...)
Отправь одно из следующих тел запроса:
{ "name": "Edge 1 (primary)" }При переименовании значение deployment в URL заменяется на слаг нового названия, возвращаемый как deployment; старый путь возвращает 404, а serviceUrl не меняется. Пустой объект metadata очищает пользовательские метаданные. При замене выполняется развертывание новой версии с сохранением идентификатора развертывания, региона и URL конечной точки; если развертывание не удается, текущая версия продолжает работать. Модель для замены должна быть завершенной и иметь веса, к которым у твоего ключа есть доступ. Действие с камерой сохраняет камеру RTSP или RTSPS, для которой готовая конечная точка с пользовательскими ресурсами непрерывно выполняет инференс (см. раздел Камера в фоновом режиме); "url": null удаляет ее. Камера также удаляется при возврате к размеру по умолчанию; сохранение камеры на конечной точке стандартного размера возвращает 403. При изменении камеры возвращается 202 с status ready на время применения изменений: опрашивай развертывание, пока cameraApplying не перестанет быть true, а затем проверь camera; если изменить камеру не удастся, останется прежняя камера и будет установлено значение statusMessage. Завершенные операции возвращают 200 с status ready или stopped; если другие операции все еще выполняются, возвращается 202 с deploying или stopping.
Удалить развертывание#
DELETE /api/deployments/{owner}/{deployment}Python SDK: client.deployments.delete(owner, deployment)
Безвозвратно удаляет конечную точку инференса.
Проверка качества#
GET /api/deployments/{owner}/{deployment}/healthPython SDK: client.deployments.health(owner, deployment)
Проверяет доступность конечной точки и прогревает ее, возвращая healthy, latencyMs и код status от вышестоящего сервиса.
Запустить инференс на развертывании#
POST /api/deployments/{owner}/{deployment}/predictPython SDK: client.deployments.predict(owner, deployment, body=...)
Передает изображение или видео через выделенную конечную точку. Контракты запроса и ответа совпадают с контрактами инференса модели. Потоки с камер не проксируются; отправляй их на URL конечной точки, как описано в разделе Инференс с камеры в реальном времени.
Составная форма:
| Параметр | Тип | По умолчанию | Диапазон | Описание |
|---|---|---|---|---|
file | файл | - | - | Файл изображения или видео (обязателен, если не задан source) |
conf | float | 0.25 | 0.01 – 1.0 | Минимальный порог уверенности |
iou | float | 0.5 | 0.0 – 0.95 | Порог IoU для NMS |
imgsz | int | - | 32 – 1280 | Размер входного изображения в пикселях; по умолчанию используется размер при обучении модели (640, если он недоступен) |
normalize | bool | false | - | Возвращать координаты рамок в диапазоне от 0 до 1 |
decimals | int | 5 | 0 – 10 | Точность десятичного представления координат |
vid_stride | int | 1 | ≥ 1 | Обрабатывать каждый N-й кадр видео; для изображений параметр игнорируется |
bits | int | 8 | 8, 12, 16 | Квантование карты глубины; только для моделей оценки глубины |
source | строка | - | - | URL изображения или строка в формате base64 (альтернатива file); максимум 4 096 символов при использовании API платформы |
Получить метрики#
GET /api/deployments/{owner}/{deployment}/metricsPython SDK: client.deployments.metrics(owner, deployment)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
range | строка | 1h, 6h, 24h (по умолчанию), 7d или 30d |
sparkline | логическое значение | Возвращать краткую сводку для панели мониторинга вместо полных рядов данных (по умолчанию: false) |
view | строка | overview возвращает только метрики запросов, ошибок и задержки P95 |
Полный ответ содержит summary (общее число запросов, доля ошибок, средняя задержка, а также задержки p50/p95/p99) и timeSeries (запросы, ошибки, задержка, CPU, память, количество экземпляров). Ответ со спарклайнами возвращает requests24h (почасовое число запросов; часы без запросов не включаются), totalRequests, errorRate и avgLatencyMs (среднее значение почасовых задержек P95). При наличии view=overview в summary содержатся totalRequests, errorRate и p95LatencyMs, а в timeSeries — requests, errors и latencyP95.
Получить журналы#
GET /api/deployments/{owner}/{deployment}/logsPython SDK: client.deployments.logs(owner, deployment)
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
severity | строка | Разделенные запятыми: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY |
limit | int | Количество записей в ответе (по умолчанию: 50, максимум: 200) |
pageToken | строка | Токен пагинации из предыдущего ответа |
API агентов#
Сохраняй рабочие процессы агентов и управляй ими. API хранит определения агентов; запуски начинаются на холсте «Агенты», где https://platform.ultralytics.com/agents?workflow={id} открывает сохраненного агента. Для методов Python SDK требуется ultralytics-platform>=0.1.74.
Для каждой операции можно указать необязательный параметр запроса owner с именем пользователя рабочего пространства, в котором ты состоишь (по умолчанию используется твое рабочее пространство). Для просмотра нужен доступ уровня Viewer; для сохранения и удаления — уровня Editor.
Получить список агентов#
GET /api/workflowsPython SDK: client.agents.list()
| Параметр | Тип | Описание |
|---|---|---|
owner | строка | Имя пользователя рабочего пространства (по умолчанию — твое) |
id | строка | Вернуть одного агента вместе с его graph |
search | строка | Фильтр по имени агента |
В ответе перечисляется до 100 агентов в workflows, сначала недавно обновленные. Для каждого агента указаны id, username, name, version, createdAt и updatedAt. Если запросить id, также возвращается graph агента.
Сохранить агента#
PUT /api/workflowsPython SDK: client.agents.save(name=..., graph=..., version=...)
Отправь version: 0, чтобы создать агента. Чтобы обновить агента, отправь его id и version, полученный при последнем запросе списка или сохранении; устаревший version возвращает 409, поэтому снова запроси агента и повтори попытку. Если связи в графе образуют цикл или у блока больше одного входа, возвращается 400.
from ultralytics_platform import Platform
def block(node_id, kind, x, config):
return {
"id": node_id,
"type": "agent",
"position": {"x": x, "y": 0},
"data": {"label": kind, "type": kind, "config": config},
}
graph = {
"nodes": [
block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
block("output", "Output", 440, {}),
],
"edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
"templateId": "",
}
with Platform() as client:
saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
print(saved["id"], saved["version"], saved["errors"])В ответе возвращаются агент id, его новый version и errors: блоки, которые холст отметил бы, например блок Dataset, для которого не выбран набор данных. Агент сохраняется в любом случае. Список всех типов блоков и их конфигураций см. в openapi.json.
Удалить агента#
DELETE /api/workflows?id={id}Python SDK: client.agents.delete(id=...)
Удаляет агента и отменяет его активные запуски. Удаленные агенты не отображаются в корзине, и восстановить их нельзя.
API корзины#
Просматривай, восстанавливай и безвозвратно удаляй мягко удаленные проекты, наборы данных и модели. Элементы автоматически удаляются окончательно через 30 дней. См. документацию по корзине.
Получить список элементов в корзине#
GET /api/trashPython SDK: client.lifecycle.trash()
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
type | строка | all (по умолчанию), project, dataset или model |
page | int | Номер страницы (по умолчанию: 1) |
limit | int | Элементов на странице (по умолчанию: 50, максимум: 200) |
id | строка | Если указать type project или model, можно предварительно просмотреть модели и развертывания, на которые повлияет удаление |
Ответ содержит items (для каждого элемента указано daysRemaining), total, page, limit, totalPages и summary с общим количеством элементов по типам. Если указать id, вместо этого возвращается resources: модели, которых коснется действие, и развертывания, которые будут безвозвратно удалены.
Восстановить элемент#
POST /api/trashPython SDK: client.lifecycle.restore(id=..., type=...)
{
"id": "65f1c0a2b3d4e5f601234567",
"type": "dataset"
}При восстановлении проекта также восстанавливаются модели, удаленные вместе с ним; они перечислены в restoredModels.
Удалить безвозвратно#
DELETE /api/trashPython SDK: client.lifecycle.delete_trash(body=...)
Удалить один элемент:
{
"id": "65f1c0a2b3d4e5f601234567",
"type": "dataset"
}Или очистить всю корзину:
{
"all": true
}В ответе указывается deletedCount, а также cascadedModels и survivingDeployments, если применимо.
Безвозвратное удаление нельзя отменить. Ресурс и все связанные с ним данные будут удалены.
API загрузки#
Загружай файлы напрямую в облачное хранилище с помощью подписанных URL. Завершение загрузки модели прикрепляет ее веса; при завершении загрузки архива набора данных проверяется его содержимое, после чего передай сессию в импорт набора данных. Если пропустить этот шаг, загрузка также завершится автоматически. См. документацию по данным.
Получить подписанный URL для загрузки#
POST /api/upload/signed-urlPython SDK: client.upload.signed_url(body=...)
Тело запроса:
{
"assetType": "datasets",
"assetId": "65f1c0a2b3d4e5f601234567",
"filename": "warehouse.zip",
"contentType": "application/zip",
"totalBytes": 52428800
}| Поле | Тип | Обязательный параметр | Описание |
|---|---|---|---|
assetType | строка | Да | datasets или models |
assetId | строка | Да | ID целевого набора данных или модели |
filename | строка | Да | Исходное имя файла (максимум 256 символов) |
contentType | строка | Да | Тип MIME |
totalBytes | число | Да | Размер файла в байтах |
Если assetType имеет значение datasets, имя filename должно оканчиваться на .zip, .tar, .tar.gz, .tgz или .ndjson. Перед загрузкой упакуй отдельные изображения в архив.
Ответ:
{
"sessionId": "session_abc123",
"uploadUrl": "https://storage.googleapis.com/...&signature=...",
"expiresAt": "2026-02-22T12:00:00Z",
"headers": { "x-goog-if-generation-match": "0" }
}Загрузи файл запросом PUT на uploadUrl, используя то же значение Content-Type, которое ты указал, и все заголовки из headers. URL для загрузки наборов данных действуют 12 часов и позволяют создать файл только один раз: повторный PUT на тот же URL возвращает 412, а PUT без полученных заголовков возвращает 400.
Завершить загрузку#
POST /api/upload/completePython SDK: client.upload.complete(session_id=...)
{
"sessionId": "session_abc123",
"md5": "<optional md5 hex>"
}Ответ: success и объект file с size и contentType. Для моделей это прикрепляет веса; для архивов наборов данных затем вызови импорт, чтобы начать обработку.
Если передан md5, его значение сверяется с сохраненным объектом. При несовпадении возвращается 400; если сессия еще не завершена, загруженный файл также удаляется, а сессия остается незавершенной. Запроси новый подписанный URL и загрузи файл повторно. Завершенную сессию набора данных можно завершить повторно, пока архив существует, но при конкурирующих запросах на завершение с разными дайджестами возвращается 409; сессии моделей удаляются при завершении. checksum сохраняется как метаданные файла модели и не проверяется.
API интеграций с хранилищами#
Подключай аккаунты Google Cloud Storage, Amazon S3 или Azure Blob Storage, просматривай их как источники наборов данных и включай или выключай функции ИИ. См. документацию по интеграциям.
Для обнаружения и подключения хранилищ нужен доступ администратора рабочего пространства и тарифный план Pro или Enterprise (иначе 403); для просмотра интеграций и объектов нужен доступ уровня Editor.
Получить список интеграций#
GET /api/integrations/bucketsPython SDK: client.storage_integrations.list()
Возвращает integrations, каждый элемент содержит id, provider, credentialIdentity, targets, processing (включены ли функции ИИ) и createdAt. Учётные данные никогда не возвращаются.
Обнаружить расположения#
POST /api/integrations/buckets/discoverPython SDK: client.storage_integrations.discover(body=...)
Перечисляет бакеты или контейнеры, доступные для чтения с указанными учетными данными, не сохраняя их.
{
"provider": "gcs",
"credentials": {
"client_email": "svc@project.iam.gserviceaccount.com",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"project_id": "my-project"
}
}Ответ: {"targets": ["my-bucket", "another-bucket"]}
Подключить хранилище#
POST /api/integrations/bucketsPython SDK: client.storage_integrations.create(body=...)
Те же структуры учётных данных, что и при обнаружении, плюс обязательный массив targets из 1–50 имён контейнеров или бакетов. Возвращает 201 с сохранённой интеграцией. При подключении проверяется право записи для каждого целевого ресурса, но ничего не записывается. Временные учётные данные S3 (ключи доступа ASIA) отклоняются.
Просмотреть объекты#
GET /api/integrations/buckets/{id}/objectsPython SDK: client.storage_integrations.objects(id, target=...)
Параметры запроса:
| Параметр | Тип | Обязательный параметр | Описание |
|---|---|---|---|
target | строка | Да | Имя бакета или контейнера |
prefix | строка | Нет | Префикс папки (максимум 1024 символа) |
cursor | строка | Нет | Курсор пагинации провайдера с предыдущей страницы |
Возвращает entries (каждый kind имеет значение folder или file) и необязательный cursor для следующей страницы.
Настройка функций ИИ#
PATCH /api/integrations/buckets/{id}Python SDK: client.storage_integrations.update(id, processing=False)
Включает ({"processing": true}) или выключает функции ИИ для всех целевых ресурсов интеграции и возвращает обновлённую интеграцию. При выключении новые задачи прекращаются. Требуется доступ администратора рабочего пространства.
Отключить хранилище#
DELETE /api/integrations/buckets/{id}Python SDK: client.storage_integrations.delete(id)
Удаляет сохраненные учетные данные, не затрагивая данные у провайдера. Подключенные наборы данных остаются видимыми, но доступ к их файлам будет закрыт, пока ты снова не подключишь ту же учетную запись хранилища. Требуется доступ администратора рабочего пространства.
API импорта наборов данных#
Импортируй датасеты из сторонних сервисов. См. интеграции с Roboflow и Label Studio.
Предварительный просмотр импорта из Roboflow#
POST /api/integrations/roboflow/previewPython SDK: client.datasets.preview_roboflow(api_key=...)
Преобразует API-ключ Roboflow в план импорта: сведения о рабочем пространстве, newDatasets, которые будут импортированы, importedDatasets, последняя версия которых уже импортирована, количество уже импортированных (skippedCount), проектов без версии, неподдерживаемых и неразрешённых проектов, bytesTotal и доступный запас storage. Для новых датасетов указывается размер их экспорта sizeBytes; для уже импортированных датасетов — если размер экспорта ещё можно определить. Параметр apiKey необязателен: если его не указать, используется сохранённый ключ Roboflow рабочего пространства, а если нет ни его, ни сохранённого ключа, запрос вернёт 400. Ключ, переданный владельцем рабочего пространства, сохраняется для рабочего пространства после определения рабочего пространства Roboflow.
{
"apiKey": "ROBOFLOW_API_KEY"
}Импорт из Roboflow#
POST /api/integrations/roboflow/importPython SDK: client.datasets.import_roboflow(api_key=..., items=...)
Ставит в очередь задачи импорта для не более чем 500 выбранных версий проектов Roboflow, используя элементы, возвращённые предварительным просмотром. Параметр apiKey необязателен; если его не указать, как и при предварительном просмотре, используется сохранённый ключ, но сам параметр никогда не сохраняется.
{
"apiKey": "ROBOFLOW_API_KEY",
"items": [
{
"workspace": "my-workspace",
"projectId": "warehouse-safety",
"projectName": "Warehouse Safety",
"projectType": "object-detection",
"latestVersion": 4
}
]
}Ответ (201): массивы imported, failed и skipped. Для импорта нужен свободный объем хранилища, а размер каждого набора данных не должен превышать лимит размера на импорт для твоего тарифного плана.
Предварительный просмотр импорта из Label Studio#
POST /api/integrations/label-studio/previewPython SDK: client.datasets.preview_label_studio(api_key=...)
Отображает проекты подключённой учётной записи размещённого Label Studio в виде плана импорта: newDatasets и importedDatasets (для каждого указаны projectId, projectName, прогнозируемое task и imageCount), unsupportedCount — проекты с неподдерживаемой конфигурацией разметки, а также storage. apiKey — необязательный персональный токен доступа или устаревший токен Label Studio: если его нет, используется сохранённый токен рабочего пространства, а если нет ни одного токена, запрос возвращает 409. Токен может передать только владелец рабочего пространства; он сохраняется для рабочего пространства после вывода списка проектов. Любой другой пользователь, передавший токен, получит 403.
{
"apiKey": "LABEL_STUDIO_ACCESS_TOKEN"
}Импорт из Label Studio#
POST /api/integrations/label-studio/importPython SDK: client.datasets.import_label_studio(project_ids=...)
Ставит в очередь импорт одного датасета для каждого из не более чем 500 идентификаторов проектов Label Studio, используя сохранённый токен рабочего пространства. Задача повторно считывается из конфигурации разметки каждого проекта, поэтому выбрать её в запросе нельзя.
{
"projectIds": [101, 102]
}Ответ (201): массивы imported, failed и skipped. Для импорта требуется свободное место в хранилище; каждому проекту выделяется равная доля этого места, ограниченная лимитом размера импорта для твоего плана.
API учетной записи#
Просматривай учетную запись Platform, ключи, хранилище и публичные профили. См. документацию по настройкам.
Сводка по учетной записи#
GET /api/account/summaryPython SDK: client.account.summary()
Возвращает тарифный план, остаток кредитов и количество ресурсов для рабочего пространства, выдавшего ключ.
{
"username": "acme-vision",
"name": "Acme Vision",
"accountType": "team",
"plan": "pro",
"creditsCents": 2500,
"counts": { "projects": 4, "datasets": 7, "models": 21 },
"teams": []
}Для личной учетной записи teams перечисляет командные рабочие пространства, в которых ты состоишь, и для каждого указывает твой role и deniedReason, если рабочее пространство сейчас недоступно, например после истечения срока действия его тарифного плана. Для командных рабочих пространств возвращается пустой список.
Получить список ключей API#
GET /api/api-keysPython SDK: client.account.api_keys()
Возвращает keys с полями keyId, name, keyPrefix и createdAt для рабочего пространства ключа. Запросы с аутентификацией по ключу API получают только метаданные; полные значения ключей видны владельцу рабочего пространства в интерфейсе Platform в разделе Настройки > Ключи API, где также можно создавать и отзывать ключи.
Проверить использование хранилища#
GET /api/storagePython SDK: client.account.storage()
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
details | логическое значение | Включить десять самых крупных потребителей хранилища (по умолчанию: false) |
Ответ:
{
"tier": "pro",
"usage": {
"storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
"datasets": { "current": 2, "limit": -1, "percent": 0 },
"models": { "current": 4, "limit": 500, "percent": 1 }
},
"breakdown": {
"byCategory": {
"datasets": { "bytes": 536870912, "count": 2 },
"models": { "bytes": 268435456, "count": 4 },
"exports": { "bytes": 268435456, "count": 3 }
},
"topItems": [
{
"_id": "65f1c0a2b3d4e5f601234567",
"name": "Warehouse",
"slug": "warehouse",
"sizeBytes": 536870912,
"type": "dataset"
}
]
},
"region": "us",
"username": "acme-vision",
"updatedAt": "2026-01-15T10:00:00Z"
}usage сообщает количество projects, datasets, models, images, annotations и deployments, а также размер в байтах для storage. Значение limit равное -1 означает отсутствие ограничений, а percent — это процент от лимита, выраженный целым числом.
Получить публичный профиль пользователя#
GET /api/usersPython SDK: client.account.profile(username=...)
Параметры запроса:
| Параметр | Тип | Обязательный параметр | Описание |
|---|---|---|---|
username | строка | Да | Имя пользователя для поиска |
Возвращает публичный профиль user с followerCount и, для пользователей с аутентификацией, isFollowed.
Подписаться на пользователя или отменить подписку#
PATCH /api/usersPython SDK: client.account.follow(username=..., followed=...)
{
"username": "target-user",
"followed": true
}Ответ: followed и обновленный followerCount.
API биллинга#
Проверяй использование тарифного плана и журнал операций с кредитами. См. документацию по биллингу.
Суммы биллинга указаны целыми числами в центах США, где 100 = $1.00.
Просмотр тарифного плана и использования#
GET /api/billing/usage-summaryPython SDK: client.billing.usage_summary()
Возвращает plan (идентификатор, статус, расчетный период, окончание периода), metrics (лимит хранилища и его использование), trainingCredit, features, creditsCents и количество мест.
Просмотр транзакций#
GET /api/billing/transactionsPython SDK: client.billing.transactions()
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
from | строка | Временная метка самой ранней транзакции (ISO 8601) |
to | строка | Временная метка самой поздней транзакции (ISO 8601) |
Каждая транзакция включает id, type (например, purchase, training, monthly_grant или refund), amountCents, balanceAfter, createdAt, необязательный receiptUrl и контекст модели для платы за обучение. Внутренние сведения о биллинге никогда не возвращаются.
API раздела Explore#
Ищи общедоступные проекты, датасеты и модели, которыми поделилось сообщество, или ищи изображения по их содержимому либо по фотографии. См. документацию раздела «Изучить».
Поиск общедоступного контента#
GET /api/explore/searchPython SDK: client.explore.search()
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
q | строка | Поисковый запрос (не более 200 символов); для датасетов и моделей сначала выполняется поиск по тексту, затем по изображениям датасетов, соответствующим запросу (или по моделям, обученным на этих датасетах) |
type | строка | all (по умолчанию; проекты и датасеты), projects, datasets, models или images (не учитывает sort) |
sort | строка | relevance (по умолчанию), newest, oldest, stars, name-asc, name-desc, count-desc, count-asc; relevance ранжирует совпадения для датасетов и моделей по q, в остальных случаях — сначала самые новые |
offset | int | Количество результатов, которые нужно пропустить (по умолчанию: 0) |
limit | int | Максимальное количество результатов для каждого типа ресурса (по умолчанию: 20, максимум: 100) |
task | строка | Фильтры задач через запятую: detect, segment, semantic, depth, classify, pose, obb |
license | строка | Разделённые запятыми идентификаторы лицензий, например CC-BY-4.0,MIT; изображения соответствуют лицензии своего датасета |
author | строка | Фильтр по имени пользователя-владельца |
starred | логическое значение | Возвращать только контент, добавленный в избранное аутентифицированным пользователем; требуется API-ключ |
minImages | int | Возвращать только датасеты, содержащие не меньше этого числа изображений; с type=images — только изображения из таких датасетов |
maxImages | int | Возвращать только датасеты, содержащие не больше этого числа изображений; с type=images — только изображения из таких датасетов |
Ответ: projects, datasets и hasMore. type=images возвращает совпадения в images, начиная с лучшего; каждое содержит исходное dataset и оценку сходства от 0 до 1 score. С q выполняется поиск по общедоступным датасетам, а также по твоим личным и командным датасетам, если ты передашь ключ API. Без q возвращается по одному изображению из каждого из новейших общедоступных датасетов, без сортировки, с score 1 и с учётом фильтров.
type=models возвращает общедоступные модели в models, по одной на обучающий датасет (или на проект, если датасета нет), кроме официальных моделей @ultralytics, для каждой из которых создаётся отдельная запись; клоны и модели, обучение которых ещё не завершено, не включаются. При наличии q сначала отображаются подходящие официальные модели, затем модели, название или проект которых соответствует запросу, а затем модели, обученные на общедоступных датасетах с наиболее подходящими изображениями. Без q выводятся модели, обученные на общедоступных датасетах, начиная с самых новых. Учитываются task и author; сортировка выполняется по relevance, newest или oldest; при любой другой сортировке сначала отображаются самые новые модели.
curl "https://platform.ultralytics.com/api/explore/search?type=datasets&task=detect&sort=stars&limit=20"Поиск по изображению#
POST /api/explore/searchPython SDK: client.explore.search_by_image() (ultralytics-platform>=0.1.107)
Отправь фотографию в формате base64 image (не более 3 MiB, не сохраняется) в теле JSON-запроса с type images (по умолчанию), datasets или models, а также любыми параметрами из sort, offset, limit, task, license, author, starred, minImages и maxImages в запросе поиска общедоступных материалов. Ответ имеет ту же структуру, а запрос с image также возвращает vector: передавай этот параметр вместо image, чтобы получить следующие страницы, применить другие фильтры или выполнить новый поиск по type, не отправляя фотографию повторно. type=images возвращает изображения с оценками, как и текстовый поиск; type=datasets возвращает общедоступные датасеты с подходящими изображениями, сначала наиболее подходящие при сортировке по умолчанию sort=relevance (при других параметрах сортировки датасеты упорядочиваются обычным образом), а эти изображения показаны на карточке каждого датасета sampleImages; type=models возвращает общедоступные модели, обученные на этих датасетах, сначала наиболее подходящие. Каждый запрос с image также учитывается в отдельном лимите: 20 запросов в минуту на пользователя (по IP-адресу, если API-ключ не указан). 400 означает, что параметры недопустимы или фотографию не удалось прочитать, а 503 — что поиск перегружен; повтори попытку чуть позже.
Python SDK#
ultralytics-platform — типизированный клиент Python, сгенерированный на основе контракта OpenAPI, с отдельным методом для каждой конечной точки (client.datasets.list, client.models.predict, client.exports.create, ...). Каждый метод принимает параметры пути позиционно, другие входные данные — как именованные аргументы, а также необязательные timeout и extra_headers для каждого запроса.
pip install "ultralytics-platform>=0.1.45" # Python 3.11+from ultralytics_platform import Platform
with Platform() as client: # читает ULTRALYTICS_API_KEY или ключ, сохранённый командой yolo login
dataset = client.datasets.retrieve("acme-vision", "warehouse")
images = client.datasets.images("acme-vision", "warehouse", limit=10)
export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")AsyncPlatform предоставляет то же дерево ресурсов для кода async/await, неуспешные ответы вызывают APIError с status_code, body и разобранным json, а ошибки подключения вызывают APIConnectionError. Полный README см. в репозитории SDK.
Интеграция с Python#
Для сценариев обучения и инференса используй пакет Ultralytics для Python: он автоматически обрабатывает аутентификацию, загрузку файлов и передачу метрик в реальном времени. В Python 3.11+ pip install ultralytics также устанавливает SDK ultralytics-platform. Когда model.train(project=...) указывает на Platform, колбэки обучения передают события через client.training.metrics() SDK и запрашивают URL для загрузки контрольных точек через client.models.upload_checkpoint() — операции POST /api/webhooks/training/metrics и POST /api/webhooks/models/upload в документе OpenAPI, поэтому тебе не нужно вызывать их самостоятельно.
Установка и настройка#
Для интеграции с Platform требуются Python>=3.11 и ultralytics>=8.4.120:
pip install "ultralytics>=8.4.120"Проверь установку:
yolo checkАутентификация#
yolo login YOUR_API_KEYИспользование датасетов на Платформе#
Указывай датасеты с помощью URI ul://:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
# Обучение на датасете Platform
model.train(
data="ul://your-username/datasets/your-dataset",
epochs=100,
imgsz=640,
)Формат URI:
| Шаблон | Описание |
|---|---|
ul://username/datasets/slug | Датасет |
ul://username/project/model-name | Конкретная модель |
ul://ultralytics/yolo26/yolo26n | Официальная модель |
Отправка в Platform#
Отправь результаты в проект Platform:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
# Результаты автоматически синхронизируются с Platform
model.train(
data="coco8.yaml",
epochs=100,
project="your-username/my-project",
name="experiment-1",
)Что синхронизируется:
- Метрики обучения (в реальном времени)
- Итоговые веса модели
- Графики валидации
- Вывод консоли
- Системные метрики
- Аргументы обучения и среда хоста (имя хоста, ОС, Python, оборудование, коммит git, командная строка)
Примеры API#
Загрузка модели из Platform:
# Твоя модель
model = YOLO("ul://username/project/model-name")
# Официальная модель
model = YOLO("ul://ultralytics/yolo26/yolo26n")Запуск инференса:
results = model("image.jpg")
# Доступ к результатам
for r in results:
boxes = r.boxes # Боксы детекций
masks = r.masks # Маски сегментации
keypoints = r.keypoints # Ключевые точки позы
probs = r.probs # Вероятности классовЭкспорт модели:
# Экспортируй в ONNX
model.export(format="onnx", imgsz=640, quantize=16)
# Экспортируй в TensorRT
model.export(format="engine", imgsz=640, quantize=16)
# Экспорт в CoreML
model.export(format="coreml", imgsz=640) # используй imgsz=224 для классификацииВалидация:
metrics = model.val(data="ul://username/datasets/my-dataset")
print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")Часто задаваемые вопросы#
Используй те же сегменты владельца и имени, что и в URL Platform. Модель по адресу
https://platform.ultralytics.com/acme-vision/inspection/v3указывается какGET /api/models/acme-vision/inspection/v3. Идентификаторы базы данных по-прежнему возвращаются в ответах (какid), а в некоторых маршрутах их нужно передавать напрямую: для маршрутов изображений требуетсяimageId, для загрузки файлов —assetId, аPOST /api/training/startпринимаетmodelId.Это зависит от коллекции. Большинство конечных точек списков принимает
limit:curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://platform.ultralytics.com/api/datasets/acme-vision?limit=50"Для изображений датасетов, кластеризации и поиска Explore используются
offsetвместе сlimit; в ответе указываетсяhasMore:curl "https://platform.ultralytics.com/api/explore/search?type=datasets&offset=20&limit=20&sort=stars"Для очень больших наборов изображений удобнее всего использовать курсор, возвращаемый как
nextCursor:curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://platform.ultralytics.com/api/datasets/acme-vision/warehouse/images?limit=1000&includeTotal=false&cursor=NEXT_CURSOR"Для корзины используется
page, а для журналов развёртывания — непрозрачный идентификаторpageToken, возвращаемый какnextPageToken.Да. Каждая операция на этой странице — обычный HTTPS-запрос, а полная спецификация опубликована в формате OpenAPI 3.2 по адресу platform.ultralytics.com/openapi.json, который можно передать генератору клиента для любого языка. Пакет
ultralytics-platform— это именно такой клиент: типизированный клиент, сгенерированный по спецификации. Пакетultralyticsдополняет его потоковой передачей метрик в реальном времени и автоматической загрузкой моделей при обучении и инференсе. Сценарии работы с аккаунтом, доступные только в сеансе браузера, например оформление оплаты и управление командой, остаются в интерфейсе Platform.Используй заголовок
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 RuntimeError("Rate limit exceeded")404означает, что ресурс не существует или вообще недоступен твоему ключу.403означает, что ресурс найден, но для выполнения действия нужны более широкие права, чем есть у твоего ключа: права редактора для изменения датасета, права владельца для удаления развёртывания, права администратора для отключения хранилища или тарифный план либо квота более высокого уровня для экспорта и развёртываний.Чтение общедоступных наборов данных, проектов и моделей, включая изображения, подписанные URL изображений, статистику классов, состояние эмбеддингов, схему кластеризации, модели, обученные на наборе данных, и список экспортов; проверка хода обучения общедоступной модели; скачивание файлов общедоступной модели; создание ссылки для мобильного импорта экспорта общедоступной модели; запуск инференса на общедоступной модели; просмотр общедоступного профиля пользователя; просмотр развёртываний с фильтром по одной общедоступной модели; поиск в Explore.
GET /api/training/gpu-availabilityполностью открыт, если только ты не запрашиваешь управляемые вычислительные ресурсы. Для всего остального нужен ключ, а его передача в общедоступный эндпоинт также раскрывает доступ к твоим приватным ресурсам.
Комментарии
Задай вопрос, поделись результатами или помоги кому-нибудь.