English | 简体中文

🔌 Ultralytics SDKs

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

🐍 Python

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-platform

Pass 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.

🧩 One Contract, Multiple Outputs

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.

🛠️ Validation

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 formats and lints Python, compiles the package, builds its wheel, installs through the Git subdirectory boundary, and exercises representative sync and async requests against a mock transport. Package releases use exactly MAJOR.MINOR.PATCH; SDK-only changes increment the patch number automatically. Both publish ultralytics-platform to PyPI through trusted publishing.

Generator improvements follow ultralytics/openapi main through the existing daily synchronization. When generated output changes without a newer contract version, synchronization increments the SDK patch number automatically. Newer contract versions are adopted; equal or older contract versions never downgrade or reuse an SDK release number. Both paths use the existing validation and publishing workflows.

💡 Contribute

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.

📄 License

• 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.

📫 Contact

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!