Public APIs Overview

Omniverse Cloud Platform-as-a-Service APIs

Overview

Omniverse Cloud Product Page : For more information on Omniverse Cloud

Note

Please Contact Us

Cloud API Streaming Sample : A sample demonstrating the use of the Omniverse Cloud Application and Streaming APIs

Current Public APIs:

• Application API - Used to query which applications are available in an Omniverse Cloud instance.

• Application Streaming API - Used to initiate and manage application streams for an Omniverse Cloud instance.

Important

To use Omniverse Cloud Platform-as-a-Service and its APIs, an Omniverse Cloud instance with an active entitlement is required.

There are three primary uses for the Omniverse Cloud Platform-as-a-Service APIs:

1. Getting information about applications installed to an Omniverse Cloud instance.

2. Getting information about active application streams running within an Omniverse Cloud instance.

3. Embedding an application stream into your own custom web environment/application, bypassing the Omniverse Cloud Web Launcher.

The Omniverse Cloud Web Launcher uses the Application APIs to query all of the available applications and their versions and then the Application Streaming API to launch the desired application version. In this example, there is just one application available, USD Explorer, with multiple versions available via the drop-down to the right.

Tip

17. I just want to publish my kit application to Omniverse Cloud and have it runnable via the Web Launcher. Do I need to use the Public APIs?

1. No. Once it is published to an Omniverse Cloud instance, your application is ready-to-go. The Web Launcher takes care of everything required to stream your application to your end-users by using the Public APIs internally.

Application Streaming on Omniverse Cloud, an Introduction

One of the key capabilities of Omniverse Cloud is running applications remotely on NVIDIA OVX hardware, accessed through a browser. This means end-users no longer need a high performance local machine—they can leverage the full potential of USD within a scalable, high-performance clustered computing environment.

Important

Omniverse Cloud provides application streaming not desktop streaming; only the contents of the application window are accessible.

Application streaming is available for any interactive kit-based application deployed to Omniverse Cloud. The Omniverse team has created extensions to enable pixel streaming and remote application control. The Application Streaming service is used to initiate and manage the application streams. The only thing required is a compatible web-browser and a suitable internet connection.

When initiating a stream, the Application Streaming service launches the chosen application on an OVX node in an Omniverse Cloud instance, enabling the streaming extension and remote control. The launch can be tailored with application specific arguments, such as a USD stage to load. Developers can also query and manage live streams, gaining insights into how the cloud platform is utilized.

For a developer to initiate a stream, they must specify a valid application and version. The Application Service is used to do so. It provides information about accessible applications, versions, and releases. Once the application and version is confirmed, developers can commence the stream through the Application Streaming service.

The following are typical high-level steps involved in initiating an application stream:

1. A developer queries the application service via the public Application API to ensure the application is available

2. The developer then initiates an application stream using the public Application Streaming API, specifying the application to execute, the USD stage to load and any additional application arguments

3. The application streaming service:

   1. Executes the application container on an OVX node, passing any specified arguments

   2. Ensures the streaming kit extension is loaded

   3. Enables bi-directional communication between the application running within the Omniverse Cloud instance and the web-application it is being streamed into.

The Application Public APIs

The application public APIs focus on three areas:

• Applications - Managing the list of applications available in an Omniverse Cloud instance.

• Application Releases - Managing individual application releases.

• Application Versions - Managing versions of an application.

The main purpose of these APIs is querying the applications, releases and versions in an Omniverse Cloud instance. The primary user is the Omniverse Cloud Web Launcher, which most end-users use to launch applications for streaming. The Web Launcher uses the Application API to see which applications and versions are available, then displays them to users.

Developers wanting to integrate Omniverse Cloud Application Streams into custom web environments, can use the Application APIs to return which applications are available or if a specific application is. Once a valid application and version are identified, they can be used to initiate the stream with the Application Streaming API.

Important

Developers should never assume that an application and application version are available. The Application APIs should always be used to verify that the desired application is installed as well as the applicable version, or to query which versions are available for a given application.

For more information about how to access the Public API reference documentation and the Application API end-points, read the Accessing the API reference documentation section, below

The Application Streaming API

The Application Streaming API provides a mechanism for querying active application streams for a specific Omniverse Cloud instance and managing new streams for developers who wish to integrate Omniverse Cloud Application streams into their own application environments.

Note

It is not required to use any public apis to deploy and stream a custom kit-based application to an Omniverse Cloud instance and have it accessible via the Omniverse Cloud Web Launcher. For more information refer to the “Publishing an Application” Omniverse Cloud Development guide

All application streams for an Omniverse Cloud instance are initiated by the Application Streaming API. These streams can be examined through the API, regardless of their origin, be it the Omniverse Cloud Web Launcher or a custom application. For example, the Monitor tab of the Web Launcher uses this API to display the list of active application streams.

Initiating an application stream is only required when a developer needs to embed a streamed Omniverse Cloud application into their own application or environment.

Note

NVIDIA’s growing suite of specialized technologies, like 3D product configurators for the global GFN network, reduces the need for direct Public API usage.

A common use case is a web application within a larger platform requiring high-fidelity visualization of complex 3D data beyond the local client’s computing abilities. A custom application, quickly built by harnessing Kit’s modularity and using Foundation applications as a base, is deployed to an Omniverse Cloud instance for this purpose.

After deployment, a web application can utilize the Public APIs to verify the application version’s availability and initiate a stream via the streaming service. The web developer can control how the stream is initiated, embedded and terminated.

For a tutorial on building a basic web application that streams from an Omniverse Cloud instance, see our “Cloud API Streaming Sample” project.

For simplicity, the tutorial uses the NVIDIA USD Explorer Foundation application as the application to be streamed. This allows you to focus on understanding how to use the Public APIs, without the need to first create your own custom kit-application and deploying it to an Omniverse Cloud instance.

For more information about how to access the Public API reference documentation and the Application API end-points, read the Accessing the API reference documentation section, below

Accessing and Authenticating the Public APIs

Now that you have an understanding of the Public APIs, let’s explore how to access your Omniverse Cloud instance, locate the API endpoints, and manage authentication.

Your Omniverse Cloud URL

Omniverse Cloud URLs take the form: [ovc_instance].cloud.omniverse.nvidia.com

The [ovc_instance] portion is determined during the setup process; ensure you verify the correct Omniverse Cloud URL for your instance. Additionally, the service endpoints are housed under a .az sub-domain, as shown below.

Accessing your Omniverse Cloud Instance

To gain access to an Omniverse Cloud Instance, you must first obtain an Omniverse Cloud entitlement. Following your purchase, the Omniverse team works with your IT and security departments to launch your Omniverse Cloud instance. This setup covers authentication, networking, and storage integration.

Once completed, you’ll receive a URL for access, usually formatted as follows:

[ovc_instance].cloud.omniverse.nvidia.com

Accessing the API reference documentation

We provide direct access to the OpenAPI specification of the Public APIs deployed to your Omniverse Cloud instance.

OpenAPI reference documentation URL:

api.[ovc_instance].az.cloud.omniverse.nvidia.com/omni/cloud/api/docs

If you do not have an active Omniverse Cloud instance to access the deployed OpenAPI documentation, you can review our non-interactive reference documentation:

• Application API

• Application Streaming API

Accessing the API end-points

The APIs themselves are accessed at:

Streaming API endpoint:

api.[ovc_instance].az.cloud.omniverse.nvidia.com/omni/cloud/api/stream/v2

Application API endpoint:

api.[ovc_instance].az.cloud.omniverse.nvidia.com/omni/cloud/api/application/v2

The APIs are major versioned, currently at v2, although they can be versioned independently. The OpenAPI documentation, mentioned above, will indicate, per service, which version is currently deployed to your instance.

Authentication

Anyone attempting to access an Omniverse Cloud instance must be properly authenticated, including when accessing the Public APIs.

Omniverse Cloud uses NVIDIA’s Starfleet to manage authentication and authorization, which can be integrated with a customer’s existing Identity Provider to enable SSO. Industry standard processes are used to authenticate, authorize and provide the user with auth and refresh tokens.

Accessing a Nucleus Server for Authentication

A javascript library is provided in the Cloud API Streaming Sample and a python cli tutorial will be completed shortly.

This authentication/authorisation flow runs through the Nucleus authorisation service. Developers accessing the Public APIs need to use python or javascript libraries that use the Nucleus protocol.

Using those libraries, the user authenticates with the service, usually hosted at:

store.[ovc_instance].az.cloud.omniverse.nvidia.com

A login url is extracted from the communication with the nucleus authentication service.

The user is expected to open this URL and go through the authentication flow. As a result, they will obtain an auth_token and refresh_token. The user is expected to use the auth_token as a Bearer token and pass this through when querying any of the APIs.

A similar flow is used to connect to a Bridged nucleus server.

Using the same libraries as mentioned previously, the user will authenticate with the bridged nucleus server. The token retrieved will then be passed as arguments to when the stream is started.

If, for example, the server is nucleus.mycompany.com and the authorisation token retrieved is eFcd the payload to start the stream would be:

{
    "application": "usd-composer",
    "application_version": "2023.2.1",
    "application_arguments": {
        "usd_stage_uri": "omniverse://store.[ovc_instance].az.omniverse.nvidia.com/project-a/stage.usd","nucleus_connection_config": [
            {
                "nucleus_server_uri":"omniverse://nucleus.mycompany.com",
                "access_token": "eFcd"
            }
        ]
    }
}

Headless Authentication

For service account/headless authentication, Starfleet Service Account (SSA) credentials are required. Once provided, the SSA ClientID and ClientSecret can be used to headlessly authenticate with a Nucleus server.

Contact NVIDIA to request SSA credentials.

Sample Python code to obtain an authorisation token after having configured SSA:

async def get_service_token(endpoint: str, scope: str, client_id: str, client_secret: str) -> str:
async with ClientSession() as session:
    url = f"{endpoint}/.well-known/oauth-authorization-server"
    print(f"Get authorization endpoints from {url}")
    response = await session.get(url)
    assert response.ok, f"Failed to call {url} -- {response}"
    body = await response.json()

    token_endpoint = body["token_endpoint"]
    data = {
        "grant_type": "client_credentials",
        "scope": scope
    }
    auth = base64.b64encode(f"{client_id}:{client_secret}".encode("utf-8")).decode("utf-8")
    headers = {
        "Authorization": f"Basic {auth}",
        "Content-Type": "application/x-www-form-urlencoded"
    }
    print(f"Get Starfleet Service token from {token_endpoint} ({auth})")
    response = await session.post(token_endpoint, headers=headers, data=data)
    assert response.ok, f"Failed to call {token_endpoint} -- {response}"

    body = await response.json()
    return body["access_token"]


async def ssa_authentication(server: str, token: str):
    api = f"https://{server}/omni/auth/api"
    async with ClientSession() as session:
        data = {"access_token": token}
        headers = {
            "Content-Type": "application/json"
        }

        url = f"{api}/ssa"
        print(f"Authenticate in Nucleus Auth API ({url})")
        response = await session.post(url, headers=headers, json=data)
        if response.ok:
            body = await response.json()
            return body
        else:
            raise Exception(f"Failed to authenticate in Nucleus Auth -- HTTP{response.status}")