Nebius AI Cloud SDK for Go - Nebius AI Cloud

The Nebius AI Cloud SDK for Go is a client library for working with Nebius AI Cloud resources from Go applications. It is built on gRPC and is based on the Nebius AI Cloud API. Use the SDK to manage resources, handle authentication and call Nebius AI Cloud services without building API requests manually. For documentation, see:

Supported Go versions

The SDK supports Go 1.24 and later. New SDK versions include breaking changes in the underlying libraries. If your project uses an earlier SDK version, pin the dependency to ~v0.1,<v0.2 in your go.mod file.

Installation and update

Install the SDK package:

go get github.com/nebius/gosdk

If you installed the SDK earlier, update it to the latest version:

go get -u github.com/nebius/gosdk

Initialization

Initialize the SDK by using gosdk.New:

import (
   "fmt"

   "github.com/nebius/gosdk"
)

sdk, err := gosdk.New(
   ctx,
   gosdk.WithUserAgentPrefix("<application_name>/<application_version_or_comment>"),
   /*, <other_initialization_options> */
)
if err != nil {
   return fmt.Errorf("create gosdk: %w", err)
}
defer sdk.Close()

The gosdk.New constructor initializes the SDK. However, initialization alone is not enough to send requests to Nebius AI Cloud services: the SDK must authenticate the requests. Add credentials and other required options to gosdk.New. The WithUserAgentPrefix method adds a prefix to the User-Agent header sent with each request. Use WithUserAgentPrefix to identify your application in the list of requests. The version or comment in the prefix is optional.

Authentication with a service account

For server-to-server communication, use a service account to authenticate SDK requests. The SDK uses the service account credentials to generate a JSON Web Token, exchange it for an IAM token and refresh the IAM token in the background. To authenticate with a service account:

Create a service account.
Generate an authorized key and create a service account credentials file:
```
nebius iam auth-public-key generate \
  --service-account-id <service_account_ID> \
  --output <credentials_file_path>
```
In the command, set the following parameters:
- --service-account-id: ID of your service account.
- --output: Path to the service account credentials file, for example credentials.json.

Initialize the SDK with the service account credentials file:

import (
   "fmt"

   "github.com/nebius/gosdk"
   "github.com/nebius/gosdk/auth"
)

sdk, err := gosdk.New(
   ctx,
   gosdk.WithUserAgentPrefix("<application_name>/<application_version_or_comment>"),
   gosdk.WithCredentials(
      gosdk.ServiceAccountReader(
         auth.NewServiceAccountCredentialsFileParser(
            nil,
            "<credentials_file_path>",
         ),
      ),
   ),
)
if err != nil {
   return fmt.Errorf("create gosdk: %w", err)
}
defer sdk.Close()

The SDK also supports authentication with IAM tokens. For more information, see the Go SDK repository.

Sending a request

The SDK provides service clients grouped by Nebius AI Cloud services and API versions. For mutating operations, such as creating, updating and deleting resources, the SDK returns an operation object. If an operation is asynchronous, call Wait to wait until it is completed. The following example creates a Compute virtual machine (VM).

Create a Go file with the following code. This script already includes SDK initialization and authentication.

package main

import (
   "context"
   "fmt"

   "github.com/nebius/gosdk"
   "github.com/nebius/gosdk/auth"
   common "github.com/nebius/gosdk/proto/nebius/common/v1"
   compute "github.com/nebius/gosdk/proto/nebius/compute/v1"
)

// Run the resource creation workflow.
func main() {
   if err := CreateInstance(context.Background()); err != nil {
      panic(err)
   }
}

// CreateInstance creates a boot disk and a VM that uses it.
func CreateInstance(ctx context.Context) error {
   // Initialize the SDK with service account credentials.
   sdk, err := gosdk.New(
      ctx,
      gosdk.WithUserAgentPrefix("<application_name>/<application_version_or_comment>"),
      gosdk.WithCredentials(
         gosdk.ServiceAccountReader(
            auth.NewServiceAccountCredentialsFileParser(
               nil,
               "<credentials_file_path>",
            ),
         ),
      ),
   )
   if err != nil {
      return fmt.Errorf("create gosdk: %w", err)
   }
   defer sdk.Close()

   // Create the boot disk.
   diskOperation, err := sdk.Services().Compute().V1().Disk().Create(ctx, &compute.CreateDiskRequest{
      Metadata: &common.ResourceMetadata{
         ParentId: "<project_ID>",
         Name:     "my-boot-disk",
      },
      Spec: &compute.DiskSpec{
         Size: &compute.DiskSpec_SizeGibibytes{
            SizeGibibytes: 93,
         },
         Type: compute.DiskSpec_NETWORK_SSD,
         Source: &compute.DiskSpec_SourceImageFamily{
            SourceImageFamily: &compute.SourceImageFamily{
               ParentId:    "<project_ID>",
               ImageFamily: "<image_family_name>",
            },
         },
      },
   })
   if err != nil {
      return fmt.Errorf("create disk: %w", err)
   }

   diskOperation, err = diskOperation.Wait(ctx)
   if err != nil {
      return fmt.Errorf("wait for disk create: %w", err)
   }

   // Create the VM that uses the boot disk.
   instanceOperation, err := sdk.Services().Compute().V1().Instance().Create(ctx, &compute.CreateInstanceRequest{
      Metadata: &common.ResourceMetadata{
         ParentId: "<project_ID>",
         Name:     "my-vm",
      },
      Spec: &compute.InstanceSpec{
         Resources: &compute.ResourcesSpec{
            Platform: "<platform_name>",
            Size: &compute.ResourcesSpec_Preset{
               Preset: "<preset_name>",
            },
         },
         NetworkInterfaces: []*compute.NetworkInterfaceSpec{
            {
               Name:      "eth0",
               SubnetId:  "<subnet_ID>",
               IpAddress: &compute.IPAddress{},
            },
         },
         BootDisk: &compute.AttachedDiskSpec{
            AttachMode: compute.AttachedDiskSpec_READ_WRITE,
            Type: &compute.AttachedDiskSpec_ExistingDisk{
               ExistingDisk: &compute.ExistingDisk{
                  Id: diskOperation.ResourceID(),
               },
            },
            DeviceId: "boot-disk",
         },
      },
   })
   if err != nil {
      return fmt.Errorf("create instance: %w", err)
   }

   _, err = instanceOperation.Wait(ctx)
   if err != nil {
      return fmt.Errorf("wait for instance create: %w", err)
   }

   return nil
}

In the script, set the following parameters:

<application_name>/<application_version_or_comment>: Application or library that calls the SDK. The version or comment is optional. For more information, see Initialization.
<credentials_file_path>: Path to the service account credentials file.
<project_ID>: ID of the project where you create the resources.
<image_family_name>: Name of the boot disk image family, for example ubuntu24.04-driverless.
<platform_name>: Name of the Compute platform, for example cpu-e2.
<preset_name>: Name of the resource preset. Available presets depend on the selected platform, for example 2vcpu-8gb for cpu-e2.
<subnet_ID>: ID of the VM’s subnet.

Execute the file:
```
go run <file_name>.go
```

​Supported Go versions

​Installation and update

​Initialization

​Authentication with a service account

​Sending a request

Supported Go versions

Installation and update

Initialization

Authentication with a service account

Sending a request