Install and Configure the Client
This section explains how to install runapy, select the right client type for your environment and configure authentication.
Prerequisites
NVIDIA Run:ai control plane version ≥ 2.18 - Required for compatibility
Python version ≥ 3.8 - Required for dependency compatibility
NVIDIA Run:ai application credentials - Required to generate the
client_idandclient_secretcredentials:To create organization-level applications, see Applications
To create user-level applications, see User Applications
Installation
For SaaS environments or latest NVIDIA Run:ai control plane:
pip install runapyFor self-hosted environments, specify the minor version matching your control plane version. For example, with NVIDIA Run:ai 2.19 control plane:
To understand the versioning scheme, refer to the Versioning section.
Client Types
The Python client provides multiple client types tailored to different environments:
ApiClient- Standard synchronous client for sequential operationsThreadedApiClient- Thread-safe client for parallel operations in multithreaded environmentsAsyncApiClient- Asynchronous client forasync/awaitsupport
For additional configuration options, see Client configuration options.
Standard API Client
The below shows a basic example using the standard client:
Multithreaded Operations
For parallel operations in a multithreaded environment, use ThreadedApiClient:
Asynchronous Operations
For async/await support, use AsyncApiClient:
Authentication Methods
The client supports three authentication methods:
Client Credentials
Use the client_id and client_secret from your NVIDIA Run:ai applications or user applications:
Bearer Token
Direct authentication using a bearer token:
CLI v2 Token (Bearer Token)
The CLI v2 token method is useful for:
Local development and testing
Scripts running on machines with existing CLI authentication
Maintaining consistent authentication with CLI sessions
End user operations
Requirements:
NVIDIA Run:ai CLI v2 is installed
Successful
runai logincompletedValid authentication token in CLI config
Client Configuration Options
client_id
string
Required: The NVIDIA Run:ai application client ID, usually representing the application name
client_secret
string
Required: The client secret associated with the NVIDIA Run:ai application
runai_base_url
string
Required: The base URL for the NVIDIA Run:ai instance your organization uses (e.g., https://myorg.run.ai)
bearer_token
string
Optional: Bearer token for CLIv2 compatibility. Cannot be used together with client credentials.
verify_ssl
bool
Optional: Whether to verify SSL certificates. Default is True
ssl_ca_cert
string
Optional: Path to CA certificate file
cert_file
string
Optional: Path to client certificate file
key_file
string
Optional: Path to client key file
pool_maxsize
int
Optional: Maximum number of connections to keep in pool. Default is 4
pool_size
int
Optional: Initial number of connections in pool. Defaults to pool_maxsize
retry_enabled
bool
Optional: Whether to enable request retries. Default is True
retry_max_retries
int
Optional: Maximum number of retry attempts. Default is 3
retry_backoff_factor
float
Optional: Exponential backoff factor between retries. Default is 0.5
proxy_url
string
Optional: URL for proxy server
proxy_headers
dict
Optional: Additional headers for proxy
proxy_server_name
string
Optional: SNI hostname for TLS connections
auto_refresh_token
bool
Optional: Whether to auto refresh token before expiry. Default is True
token_refresh_margin
int
Optional: Seconds before expiry to refresh token. Default is 60
debug
bool
Optional: Enable debug logging. Default is False
Last updated