gabrielmoreira Ultralytics Platform
Use ultralytics for YOLO training and inference. Use the generated ultralytics-platform Python
SDK for API resource work. It follows the same contract as the live API and handles authentication,
typed responses, retries, and errors.
Read the live contract
Before API work, check the generated API reference or
GET https://platform.ultralytics.com/openapi.json. Treat the live OpenAPI document as authoritative
when examples disagree. The shapes below match API and SDK v0.1.18, checked on 2026-08-27.
uv pip install -U "ultralytics-platform>=0.1.18"
export ULTRALYTICS_API_KEY=ul_... # Settings > API Keys
Platform() reads ULTRALYTICS_API_KEY. The ultralytics package also reads the key saved by
yolo login. Never print or commit a key.
Choose the interface
| Goal | Interface |
|---|---|
| Track a run that has not started | ultralytics training callback |
| Train with a Platform dataset or model | ultralytics with a ul:// URI |
| Manage datasets, models, training, exports, or deployments | ultralytics-platform SDK |
| Use another language or inspect a new field | Live OpenAPI |
Live training and ul:// URIs
Pass an owner-qualified project to stream a run:
from ultralytics import YOLO
YOLO("yolo26n.pt").train(data="coco8.yaml", epochs=100, project="owner/project", name="run1")
project= is required. Without it, the callback exits before creating a Platform run. Use the
owner prefix for a team workspace.
YOLO("ul://owner/project/model").train(data="ul://owner/datasets/dataset", epochs=100)
SDK
Use a context manager and owner/name paths. Keep returned IDs for operations that require them,
including image operations, upload assetId, training modelId, and export IDs.
Responses have resource-specific shapes, not a generic envelope. Create calls return id, owner,
and the URL name at the top level. Detail calls wrap the resource under its type, such as dataset.
A rename changes the URL name, so use the name returned by the update response.
Read references/recipes.md for live-run diagnosis, finished-run upload, dataset upload, and billable jobs.
Invariants
- Confirm the target workspace with
client.account.summary()and read the exact resource before a mutation. Team work requires an API key created in that workspace. - A direct upload is signed URL,
PUTwith the returnedheaders, upload completion, then dataset ingest. Model uploads stop after completion. - Dataset ingest accepts one source:
sessionId,sourceUrl, or a connected-storagereference. SettargetSplitwhen every incoming image must enter one split. - Top-level model
metricsaccepts only the contract's named summary metrics. Per-epochtrainResults[].metricsaccepts numeric metric names fromresults.csv. - On
429, wait forRetry-Afterbefore retrying. Do not invent fixed sleeps.
Cost and destructive actions
Cloud training, model exports, and deployments can spend credits. Get approval before calling
client.training.start, client.exports.create, or client.deployments.create, then report the
cost returned by the create response. Get approval before deletes. Resource deletes move projects,
datasets, and models to 30-day trash. client.lifecycle.delete_trash is permanent.