Nebius Python SDK

0.3.55 · active · verified Sat Apr 11

Nebius provides an AI Cloud platform with a Python SDK (nebius) to interact with its various services, including AI Studio for large language models and embeddings, Compute for virtual machines and GPUs, and Object Storage. The SDKs are built on gRPC and Protocol Buffers, offering programmatic access to the Nebius AI Cloud. As of January 24, 2025, the Python SDKs are generally available. The project maintains an active development pace with frequent updates, as indicated by its current version 0.3.55.

Warnings

gotcha Authentication to Nebius AI Cloud services (including AI Studio) requires an API key or an IAM access token. It is crucial to store these credentials securely, typically using environment variables, and never hardcode them in your codebase.
Fix: Store API keys as environment variables (e.g., `NEBIUS_API_KEY`) or retrieve IAM tokens dynamically using the Nebius CLI (`nebius iam get-access-token`) for secure authentication. Use `os.environ.get('YOUR_KEY_NAME')` to access them.
gotcha When provisioning Compute resources (VMs, GPUs), users may encounter 'Not enough resources' errors due to high demand in specific regions or for particular configurations. This is a common operational challenge in cloud environments.
Fix: If encountering this error, consider trying a different region, selecting a VM type or GPU with different specifications, or requesting a capacity reservation through Nebius support. Nebius is also releasing a capacity dashboard for transparency.
breaking The `Update` method for Nebius AI Cloud API resources is designed to perform a 'full-replace' of resource fields, not a 'patch' operation. To maintain compatibility and prevent unintentional modifications of unknown fields, it uses a 'Reset Mask' mechanism.
Fix: Be aware that calling an `Update` method will replace the entire resource object with the provided data. Use the 'Reset Mask' if available via the SDK (often handled automatically by the SDK) to selectively update fields and preserve others, or ensure your update payload contains all desired final states for the resource.
gotcha For Nebius AI Studio, while the native `nebius` SDK is available, many AI-focused integrations and quickstarts leverage OpenAI API compatibility. This means interacting through the standard `openai` Python client by setting a custom `base_url`.
Fix: If integrating with Nebius AI Studio for LLMs/embeddings, refer to documentation or examples that use the `openai` library with `base_url` pointing to `https://api.tokenfactory.nebius.com/v1/` (or your specific endpoint) and provide your Nebius API key.

Install

pip install nebius Install core SDK

Imports

Client

from nebius.iam.v1.iam_service_pb2_grpc import IamServiceStub
from nebius.iam.v1.iam_service_pb2 import GetUserAccountRequest
import grpc

# Note: Specific imports like these are typically generated from Nebius's .proto files.
# The `nebius` package acts as a meta-package or provides common utilities, while service clients
# are often dynamically generated or accessed through a top-level client object (not explicitly found in public searches for 'nebius' package directly).

Exact direct client imports for generic Nebius services (e.g., Compute, Storage) within the `nebius` PyPI package are not widely documented in public quickstarts. Interaction is often via generated gRPC clients from .proto definitions, or through higher-level integrations like with OpenAI for AI Studio. The example above shows a hypothetical gRPC client stub for IAM based on Nebius's public .proto definitions.

OpenAI Client (AI Studio)
```
from openai import OpenAI
```
For Nebius AI Studio, the recommended and best-documented approach is to use the standard `openai` library with a custom `base_url` to point to the Nebius AI Studio endpoint, leveraging its OpenAI compatibility. There is no direct `AIStudioClient` import from the `nebius` package itself that provides this compatibility.

Quickstart

This quickstart demonstrates how to interact with Nebius AI Studio using its OpenAI-compatible API. You will need an API key from Nebius AI Studio, preferably set as an environment variable (NEBIUS_API_KEY). The `openai` Python library is used, with the `base_url` configured to point to the Nebius AI Studio endpoint. Replace `Qwen/Qwen3-30B-A3B-fast` with an actual model available in your Nebius AI Studio account.

import os
from openai import OpenAI

# Ensure NEBIUS_API_KEY is set in your environment variables
# Example: export NEBIUS_API_KEY='YOUR_API_KEY'
# You can obtain an API key from Nebius AI Studio.
nebius_api_key = os.environ.get('NEBIUS_API_KEY', 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

if not nebius_api_key:
    print("Error: NEBIUS_API_KEY environment variable not set.")
    print("Please get your API key from Nebius AI Studio and set it.")
else:
    try:
        client = OpenAI(
            base_url="https://api.tokenfactory.nebius.com/v1/", # Or your specific Nebius AI Studio endpoint
            api_key=nebius_api_key,
        )

        chat_completion = client.chat.completions.create(
            model="Qwen/Qwen3-30B-A3B-fast", # Replace with an available model from Nebius AI Studio
            messages=[
                {"role": "user", "content": "Hello, what is your name?"}
            ]
        )
        print(chat_completion.choices[0].message.content)
    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →