Typed SDKs for the Ultralytics Platform API, generated from a pinned contract with Ultralytics OpenAPI. The interactive API reference renders the live contract directly and includes Python SDK examples.
| Output | Status |
|---|---|
| Interactive API reference | Available |
| Python SDK | Available |
| TypeScript SDK | Coming soon |
| Go SDK | Coming soon |
| Java SDK | Coming soon |
The package includes the unified ul CLI for local YOLO and Platform SDK commands; see the CLI guide. Maintain cli.py and auth.py at the repository root, then regenerate their installed copies through the configured python.cli.source and python.authProvider hooks.
Install the standalone ultralytics-platform package from PyPI in a Python >=3.11 environment. It has one lightweight runtime dependency (httpx) and does not install the larger ultralytics package:
uv pip install ultralytics-platformPass your Platform API key directly as shown below. Alternatively, omit api_key to use ULTRALYTICS_API_KEY or the Platform key saved by yolo login. Both clients use explicit credentials first, then the environment, then saved settings. Pass api_key="" to disable authentication. yolo logout removes the saved key; it does not unset an environment variable. The SDK reads the existing Ultralytics settings directory, including YOLO_CONFIG_DIR and Linux XDG_CONFIG_HOME, without importing or installing ultralytics.
from ultralytics_platform import Platform
with Platform(api_key="YOUR_API_KEY") as client:
datasets = client.datasets.list("your_username")
training = client.training.start(model_id="model_id", train_args={"epochs": 10})
model = client.models.retrieve("your_username", "project", "model")
export = client.exports.create("your_username", "project", "model", format="onnx")
deployment = client.deployments.create(
"your_username",
project="project",
model="model",
deployment="production",
name="Production",
region="us-central1",
)The asynchronous client exposes the same resource tree:
import asyncio
from ultralytics_platform import AsyncPlatform
async def main():
async with AsyncPlatform(api_key="YOUR_API_KEY") as client:
datasets = await client.datasets.list("your_username")
asyncio.run(main())The package includes typed responses, multipart uploads, retries for temporary failures, structured API errors, custom HTTP clients, and context-manager cleanup. It requires Python 3.11 or newer.
Use ul cloud train model=yolo26n.pt data=ul://you/datasets/animals to prepare and submit training with YOLO arguments. Local .pt weights and dataset paths are uploaded automatically; the command prints the run and its ul cloud download command, or add watch to follow training and download the results. This convenience command requires ultralytics in the same environment; see the CLI documentation.
Ultralytics Platform owns the API contract. This repository pins a versioned snapshot with its generated descendants:
Platform OpenAPI contract
├── openapi.json # Versioned contract snapshot
├── README.python.md # Python package README source
└── sdk/
├── python/ # ultralytics-platform
├── typescript/ # coming soon
├── go/ # coming soon
└── java/ # coming soon
openapi.config.json contains product and package configuration, including the source path for README.python.md. auth.py owns the Python SDK's Ultralytics credential discovery and is included by the generic python.authProvider hook on every regeneration. openapi.json and openapi.sha256 pin the exact consumed contract. Generated files are never edited manually; update the contract snapshot, configuration, package README source, or generator and regenerate.
CI regenerates the Python SDK from the versioned contract with the main branch of Ultralytics OpenAPI, then fails on contract mismatch or generated drift. Pushes to main, scheduled runs, and manual runs detect upstream contract changes without breaking unrelated pull requests. CI also checks Python formatting and lint, compiles the package, builds its wheel, installs through the Git subdirectory boundary, exercises representative sync and async requests against a mock transport, and saves ul cloud predict outputs offline with CPU ultralytics. Package releases use the upstream Platform API contract's info.version, exactly MAJOR.MINOR.PATCH, and publish ultralytics-platform to PyPI through trusted publishing. CI rejects independent python.version overrides and package versions that differ from the contract.
Generator improvements follow ultralytics/openapi main through the existing daily synchronization. SDK or generator changes that need a release require a contract version bump coordinated with the Platform API maintainers. Deploy the contract, then let synchronization update the snapshot and generated package; the SDK never increments its version independently.
Before raising a consumer's minimum SDK version, verify the published wheel contains the required behavior and matches the deployed API version. If an SDK version was published ahead of the API, coordinate an upstream contract version greater than every published SDK version and synchronize; never downgrade the SDK or reuse a published version.
Ultralytics thrives on community collaboration, and we deeply value your contributions! Please see our Contributing Guide for details on how you can get involved. We also encourage you to share your feedback through our Survey. A huge thank you 🙏 to all our contributors!
API shape changes belong in the Platform OpenAPI contract; generated files in this repository should not be edited directly.
- AGPL-3.0 License: The generated SDKs are licensed under the AGPL-3.0 License.
- Enterprise License: Commercial licensing is available separately through Ultralytics Licensing.
For bug reports or feature suggestions related to Ultralytics SDKs, please submit an issue via GitHub Issues. Join our Discord community for discussions and support!
