Use ultralytics for YOLO training and inference. Use the generated ultralytics-platform Python\nSDK for API resource work. It follows the same contract as the live API and handles authentication,\ntyped responses, retries, and errors.
Before API work, check the generated API reference or\nGET https://platform.ultralytics.com/openapi.json. Treat the live OpenAPI document as authoritative\nwhen 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\"\nexport ULTRALYTICS_API_KEY=ul_... # Settings > API Keys\nPlatform() reads ULTRALYTICS_API_KEY. The ultralytics package also reads the key saved by\nyolo login. Never print or commit a key.
| Goal | \nInterface | \n
|---|---|
| Track a run that has not started | \nultralytics training callback | \n
| Train with a Platform dataset or model | \nultralytics with a ul:// URI | \n
| Manage datasets, models, training, exports, or deployments | \nultralytics-platform SDK | \n
| Use another language or inspect a new field | \nLive OpenAPI | \n
ul:// URIsPass an owner-qualified project to stream a run:
\nfrom ultralytics import YOLO\n\nYOLO(\"yolo26n.pt\").train(data=\"coco8.yaml\", epochs=100, project=\"owner/project\", name=\"run1\")\nproject= is required. Without it, the callback exits before creating a Platform run. Use the\nowner prefix for a team workspace.
YOLO(\"ul://owner/project/model\").train(data=\"ul://owner/datasets/dataset\", epochs=100)\nUse a context manager and owner/name paths. Keep returned IDs for operations that require them,\nincluding image operations, upload assetId, training modelId, and export IDs.
Responses have resource-specific shapes, not a generic envelope. Create calls return id, owner,\nand the URL name at the top level. Detail calls wrap the resource under its type, such as dataset.\nA 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,\ndataset upload, and billable jobs.
\nclient.account.summary() and read the exact resource before a\nmutation. Team work requires an API key created in that workspace.PUT with the returned headers, upload completion, then dataset\ningest. Model uploads stop after completion.sessionId, sourceUrl, or a connected-storage reference.\nSet targetSplit when every incoming image must enter one split.metrics accepts only the contract's named summary metrics. Per-epoch\ntrainResults[].metrics accepts numeric metric names from results.csv.429, wait for Retry-After before retrying. Do not invent fixed sleeps.Cloud training, model exports, and deployments can spend credits. Get approval before calling\nclient.training.start, client.exports.create, or client.deployments.create, then report the\ncost returned by the create response. Get approval before deletes. Resource deletes move projects,\ndatasets, and models to 30-day trash. client.lifecycle.delete_trash is permanent.