Prerequisites
- Web console
- CLI
- Go SDK
- Python SDK
- JavaScript SDK
- REST API
-
Make sure you are in a group that has at least the
editorrole within your tenant or project; for example, the defaulteditorsgroup. You can check this in the Administration → IAM section of the web console. -
In the Administration → Limits → Quotas section, check the following quotas:
- Number of virtual machines (VMs) under Compute: make sure that at least one VM is available.
- Allocations under Virtual Networks: make sure that at least one allocation is available.
-
Install and configure the Nebius AI Cloud CLI.
Check that your project ID is saved in the Nebius AI Cloud CLI profile configuration:
cat ~/.nebius/config.yaml -
Install jq to parse JSON output:
sudo apt-get install jqbrew install jq -
Make sure that you or the service account that you use is in a group that has at least the
editorrole within your tenant or project; for example, the defaulteditorsgroup. You can check this in the Administration → IAM section of the web console. -
In the Administration → Limits → Quotas section, check the following quotas:
- Number of virtual machines (VMs) under Compute: make sure that at least one VM is available.
- Allocations under Virtual Networks: make sure that at least one allocation is available.
- Install and initialize the Nebius SDK for Go.
-
Make sure that you or the service account that you use is in a group that has at least the
editorrole within your tenant or project; for example, the defaulteditorsgroup. You can check this in the Administration → IAM section of the web console. -
In the Administration → Limits → Quotas section, check the following quotas:
- Number of virtual machines (VMs) under Compute: make sure that at least one VM is available.
- Allocations under Virtual Networks: make sure that at least one allocation is available.
- Install and initialize the Nebius SDK for Python.
-
Make sure that you or the service account that you use is in a group that has at least the
editorrole within your tenant or project; for example, the defaulteditorsgroup. You can check this in the Administration → IAM section of the web console. -
In the Administration → Limits → Quotas section, check the following quotas:
- Number of virtual machines (VMs) under Compute: make sure that at least one VM is available.
- Allocations under Virtual Networks: make sure that at least one allocation is available.
- Install and initialize the Nebius SDK for JavaScript.
-
Make sure that you or the service account that you use is in a group that has at least the
editorrole within your tenant or project; for example, the defaulteditorsgroup. You can check this in the Administration → IAM section of the web console. -
In the Administration → Limits → Quotas section, check the following quotas:
- Number of virtual machines (VMs) under Compute: make sure that at least one VM is available.
- Allocations under Virtual Networks: make sure that at least one allocation is available.
- Get an access token to authenticate to the REST API.
-
Make sure that you or the service account that you use is in a group that has at least the
editorrole within your tenant or project; for example, the defaulteditorsgroup. You can check this in the Administration → IAM section of the web console. -
In the Administration → Limits → Quotas section, check the following quotas:
- Number of virtual machines (VMs) under Compute: make sure that at least one VM is available.
- Allocations under Virtual Networks: make sure that at least one allocation is available.
Steps
Create an endpoint
- Web console
- CLI
- Go SDK
- Python SDK
- JavaScript SDK
- REST API
- In the sidebar, go to
Serverless AI → Endpoints.
- Select the nginx quick start card. The quick start configuration autofills the container image, entrypoint command, and default settings.
- Click Create endpoint.
Use
nebius ai create to create a endpoint step by step in the terminal. The command prompts you to enter values to pass as parameters, shows the resulting configuration and then creates the endpoint.-
Create a token for authorization and save it to an environment variable:
Use this token in the
export AUTH_TOKEN=$(openssl rand -hex 32)--tokenparameter when you create the endpoint. You will also need it later to test access to the endpoint. -
Run the following command:
Alternatively, you can run
nebius ai endpoint create \ --name qs-endpoint-nginx \ --image nginx:alpine \ --platform cpu-d3 \ --preset 4vcpu-16gb \ --public \ --container-port 80 \ --auth token \ --token "$AUTH_TOKEN" \ --subnet-id <subnet_ID>nebius ai createand specify each value step by step with CLI prompts. The command pre-fills the following values:--name: Endpoint name.--image: Container image to run. In the given example, thenginx:alpineimage is used.--platform: VM platform for the endpoint. Every endpoint uses Compute platforms and presets.--preset: Number of vCPUs and RAM allocated to the container. The preset must match the selected platform.--container-port: Port on which the application listens in the container. Each HTTP port is available through the managed HTTPS URL of the endpoint.--auth: Authentication method for the endpoint.--token: Token used for endpoint authentication.--public(optional): Assigns a public IP address to the endpoint. Not required to reach the endpoint from the internet, because each HTTP port is available through the endpoint’s managed HTTPS URL.--subnet-id: Subnet ID.
- When the CLI prompts you to select a project, region or subnet, select from the values that are available.
- Review the resulting configuration, then confirm creation.
-
Generate a token for endpoint authentication and store it in an
authTokenvariable, for example, withcrypto/rand:Use this token intokenBytes := make([]byte, 32) if _, err := rand.Read(tokenBytes); err != nil { return fmt.Errorf("generate endpoint token: %w", err) } authToken := hex.EncodeToString(tokenBytes)Spec.AuthTokenwhen you create the endpoint. You will also need it later to test access to the endpoint. -
Create an endpoint:
In the code, set the following parameters:
createEndpointService := sdk.Services().Ai().V1().Endpoint() createEndpointOperation, err := createEndpointService.Create( ctx, &ai.CreateEndpointRequest{ Metadata: &common.ResourceMetadata{ ParentId: "<project_ID>", Name: "qs-endpoint-nginx", }, Spec: &ai.EndpointSpec{ Image: "nginx:alpine", Platform: "cpu-d3", Preset: "4vcpu-16gb", Ports: []*ai.EndpointSpec_Port{ { ContainerPort: 80, Protocol: ai.EndpointSpec_Port_HTTP, }, }, AuthToken: authToken, PublicIp: true, SubnetId: "<subnet_ID>", Disk: &ai.EndpointSpec_DiskSpec{ Type: compute.DiskSpec_NETWORK_SSD, SizeBytes: 268435456000, }, }, }, ) if err != nil { return fmt.Errorf("create endpoint: %w", err) } if _, err = createEndpointOperation.Wait(ctx); err != nil { return fmt.Errorf("wait for endpoint creation: %w", err) }Metadata.ParentId: Project ID.Metadata.Name: Endpoint name.Spec.Image: Container image to run. In the given example, thenginx:alpineimage is used.Spec.Platform: VM platform for the endpoint. Every endpoint uses Compute platforms and presets.Spec.Preset: Number of vCPUs and RAM allocated to the container. The preset must match the selected platform.Spec.Ports[].ContainerPort: Port on which the application listens in the container. Each HTTP port is available through the endpoint’s managed HTTPS URL.Spec.Ports[].Protocol: Protocol used by the exposed port.Spec.AuthToken: Token used for endpoint authentication, generated in the previous step.Spec.PublicIp(optional): Whether to assign a public IP address to the endpoint. Not required to reach the endpoint from the internet, because each HTTP port is available through the endpoint’s managed HTTPS URL.Spec.SubnetId: Subnet ID.Spec.Disk.Type: Disk type for the underlying VM.Spec.Disk.SizeBytes: Disk size in bytes. The example sets 250 GiB.
Waitcompletes,createEndpointOperation.ResourceID()returns the created endpoint’s ID. Save this value because you need it in later steps.
-
Generate a token for endpoint authentication and store it in an
auth_tokenvariable, for example, withsecrets:Use this token inimport secrets auth_token = secrets.token_hex(32)spec.auth_tokenwhen you create the endpoint. You will also need it later to test access to the endpoint. -
Create an endpoint:
In the code, set the following parameters:
create_endpoint_service = EndpointServiceClient(sdk) create_endpoint_operation = await create_endpoint_service.create( CreateEndpointRequest( metadata=ResourceMetadata( parent_id="<project_ID>", name="qs-endpoint-nginx", ), spec=EndpointSpec( image="nginx:alpine", platform="cpu-d3", preset="4vcpu-16gb", ports=[ EndpointSpec__Port( container_port=80, protocol=( EndpointSpec__Port__Protocol.HTTP ), ), ], auth_token=auth_token, public_ip=True, subnet_id="<subnet_ID>", disk=EndpointSpec__DiskSpec( type=DiskSpec__DiskType.NETWORK_SSD, size_bytes=268435456000, ), ), ), ) await create_endpoint_operation.wait()metadata.parent_id: Project ID.metadata.name: Endpoint name.spec.image: Container image to run. In the given example, thenginx:alpineimage is used.spec.platform: VM platform for the endpoint. Every endpoint uses Compute platforms and presets.spec.preset: Number of vCPUs and RAM allocated to the container. The preset must match the selected platform.spec.ports[].container_port: Port on which the application listens in the container. Each HTTP port is available through the endpoint’s managed HTTPS URL.spec.ports[].protocol: Protocol used by the exposed port.spec.auth_token: Token used for endpoint authentication, generated in the previous step.spec.public_ip(optional): Whether to assign a public IP address to the endpoint. Not required to reach the endpoint from the internet, because each HTTP port is available through the endpoint’s managed HTTPS URL.spec.subnet_id: Subnet ID.spec.disk.type: Disk type for the underlying VM.spec.disk.size_bytes: Disk size in bytes. The example sets 250 GiB.
await create_endpoint_operation.wait()completes,create_endpoint_operation.resource_idreturns the created endpoint’s ID. Save this value because you need it in later steps.
-
Generate a token for endpoint authentication and store it in an
authTokenvariable, for example, withnode:crypto:Use this token inimport { randomBytes } from "node:crypto"; const authToken = randomBytes(32).toString("hex");spec.authTokenwhen you create the endpoint. You will also need it later to test access to the endpoint. -
Create an endpoint:
In the code, set the following parameters:
const createEndpointService = new EndpointService(sdk); const createEndpointOperation = await createEndpointService.create( CreateEndpointRequest.create({ metadata: { parentId: "<project_ID>", name: "qs-endpoint-nginx", }, spec: { image: "nginx:alpine", platform: "cpu-d3", preset: "4vcpu-16gb", ports: [{ containerPort: 80, protocol: EndpointSpec_Port_Protocol.HTTP, }], authToken, publicIp: true, subnetId: "<subnet_ID>", disk: { type: DiskSpec_DiskType.NETWORK_SSD, sizeBytes: 268435456000n, }, }, }), ).result; await createEndpointOperation.wait();metadata.parentId: Project ID.metadata.name: Endpoint name.spec.image: Container image to run. In the given example, thenginx:alpineimage is used.spec.platform: VM platform for the endpoint. Every endpoint uses Compute platforms and presets.spec.preset: Number of vCPUs and RAM allocated to the container. The preset must match the selected platform.spec.ports[].containerPort: Port on which the application listens in the container. Each HTTP port is available through the endpoint’s managed HTTPS URL.spec.ports[].protocol: Protocol used by the exposed port.spec.authToken: Token used for endpoint authentication, generated in the previous step.spec.publicIp(optional): Whether to assign a public IP address to the endpoint. Not required to reach the endpoint from the internet, because each HTTP port is available through the endpoint’s managed HTTPS URL.spec.subnetId: Subnet ID.spec.disk.type: Disk type for the underlying VM.spec.disk.sizeBytes: Disk size in bytes, as abigint. The example sets 250 GiB.
await createEndpointOperation.wait()completes,createEndpointOperation.resourceId()returns the created endpoint’s ID. Save this value because you need it in later steps.
-
Create a token for endpoint authentication:
Save the token: it is different from the access token that authorizes REST API requests, and you need it to create and test the endpoint.
openssl rand -hex 32 -
Send the following request. Specify the endpoint authentication token from the previous step in
spec.authToken:In thecurl --request POST \ --url 'https://api.nebius.cloud/ai/v1/endpoints' \ --header "Authorization: Bearer <access_token>" \ --header 'Content-Type: application/json' \ --data '{ "metadata": { "parentId": "<project_ID>", "name": "qs-endpoint-nginx" }, "spec": { "image": "nginx:alpine", "platform": "cpu-d3", "preset": "4vcpu-16gb", "ports": [ { "containerPort": 80, "protocol": "HTTP" } ], "authToken": "<endpoint_token>", "publicIp": true, "subnetId": "<subnet_ID>", "disk": { "type": "NETWORK_SSD", "sizeBytes": "268435456000" } } }'Authorizationheader, replace<access_token>with the access token that you got in the prerequisites. The request includes the following parameters:metadata.parentId: Project ID.metadata.name: Endpoint name.spec.image: Container image to run.spec.platform: VM platform for the endpoint. Every endpoint uses Compute platforms and presets.spec.preset: Number of vCPUs and RAM allocated to the container. The preset must match the selected platform.spec.ports[].containerPort: Port on which the application listens in the container.spec.ports[].protocol: Protocol used by the exposed port. An HTTP port is available through the endpoint’s managed HTTPS URL.spec.authToken: Token used for endpoint authentication.spec.publicIp(optional): Whether to assign a public IP address to the endpoint. A public IP address isn’t required to reach the endpoint through its managed HTTPS URL.spec.subnetId: Subnet ID.spec.disk.type: Disk type for the underlying VM.spec.disk.sizeBytes: Disk size in bytes. The specified value is 250 GiB.
resourceIdparameter. Save this value because you need it in later steps.
Test the endpoint
- Web console
- CLI
- Go SDK
- Python SDK
- JavaScript SDK
- REST API
-
In the sidebar, go to
Serverless AI → Endpoints.
-
Click the endpoint name to open its details. Wait until the endpoint is running. Then copy its managed HTTPS URL (
https://...) from the Public endpoints field. -
In a terminal, send a request to the endpoint:
In the command, specify the managed HTTPS URL that you copied earlier. The response should have HTTP status
curl -v <endpoint_URL>200 OK. The body is the default nginx welcome page, which confirms that the endpoint is serving traffic over the managed HTTPS URL.
-
Save the endpoint ID to an environment variable:
export ENDPOINT_ID=$(nebius ai endpoint get-by-name \ --name qs-endpoint-nginx --format jsonpath='{.metadata.id}') -
Get the endpoint’s managed HTTPS URL from the Public endpoints field:
export ENDPOINT_URL=$(nebius ai endpoint get "$ENDPOINT_ID" --format json \ | jq -r '.status.public_endpoints[] | select(startswith("https://"))' | head -1) -
Test the endpoint with authentication:
curl -v "$ENDPOINT_URL" -H "Authorization: Bearer $AUTH_TOKEN" -
Test the endpoint without a token:
The test should fail with the error
curl -v "$ENDPOINT_URL"401 Unauthorizedor403 Forbidden.
-
Get the endpoint’s managed HTTPS URL:
In
getEndpointService := sdk.Services().Ai().V1().Endpoint() endpoint, err := getEndpointService.Get( ctx, &ai.GetEndpointRequest{Id: "<endpoint_ID>"}, ) if err != nil { return fmt.Errorf("get endpoint: %w", err) } for _, address := range endpoint.GetStatus().GetPublicEndpoints() { if strings.HasPrefix(address, "https://") { fmt.Println(address) break } }ai.GetEndpointRequest, setIdto the endpoint ID that you saved when you created the endpoint. If the code prints no URL, the endpoint isn’t running yet. Wait a few seconds and run the code again. -
Test the endpoint with authentication:
Replace
curl -v <endpoint_URL> \ --header 'Authorization: Bearer <endpoint_token>'<endpoint_URL>with the URL that the code printed and<endpoint_token>with theauthTokenvalue. -
Test the endpoint without a token:
The test should fail with the error
curl -v <endpoint_URL>401 Unauthorizedor403 Forbidden.
-
Get the endpoint’s managed HTTPS URL:
In
get_endpoint_service = EndpointServiceClient(sdk) endpoint = await get_endpoint_service.get( GetEndpointRequest(id="<endpoint_ID>"), ) endpoint_url = next( ( address for address in endpoint.status.public_endpoints if address.startswith("https://") ), None, ) if endpoint_url is not None: print(endpoint_url)GetEndpointRequest, setidto the endpoint ID that you saved when you created the endpoint. If the code prints no URL, the endpoint isn’t running yet. Wait a few seconds and run the code again. -
Test the endpoint with authentication:
Replace
curl -v <endpoint_URL> \ --header 'Authorization: Bearer <endpoint_token>'<endpoint_URL>with the URL that the code printed and<endpoint_token>with theauth_tokenvalue. -
Test the endpoint without a token:
The test should fail with the error
curl -v <endpoint_URL>401 Unauthorizedor403 Forbidden.
-
Get the endpoint’s managed HTTPS URL:
In
const getEndpointService = new EndpointService(sdk); const endpoint = await getEndpointService.get( GetEndpointRequest.create({ id: "<endpoint_ID>" }), ); const endpointUrl = endpoint.status?.publicEndpoints.find( (address) => address.startsWith("https://"), ); if (endpointUrl !== undefined) { console.log(endpointUrl); }GetEndpointRequest, setidto the endpoint ID that you saved when you created the endpoint. If the code prints no URL, the endpoint isn’t running yet. Wait a few seconds and run the code again. -
Test the endpoint with authentication:
Replace
curl -v <endpoint_URL> \ --header 'Authorization: Bearer <endpoint_token>'<endpoint_URL>with the URL that the code printed and<endpoint_token>with theauthTokenvalue. -
Test the endpoint without a token:
The test should fail with the error
curl -v <endpoint_URL>401 Unauthorizedor403 Forbidden.
-
Get the endpoint:
In the request, specify:
curl --request GET \ --url "https://api.nebius.cloud/ai/v1/endpoints/<endpoint_ID>" \ --header "Authorization: Bearer <access_token>"- Your access token in the
Authorizationheader. - In the request path, the endpoint ID returned in the
resourceIdparameter when you created the endpoint.
status.stateparameter in the response. If the state isn’tRUNNING, wait a few seconds and send the request again. - Your access token in the
-
Copy a managed HTTPS URL (
https://...) from thestatus.publicEndpointsparameter in the response. -
Test the endpoint with authentication:
curl -v <endpoint_URL> \ --header 'Authorization: Bearer <endpoint_token>' -
Test the endpoint without a token:
The test should fail with the error
curl -v <endpoint_URL>401 Unauthorizedor403 Forbidden.
View logs
Viewing endpoint logs is available only in the web console and CLI.
- Web console
- CLI
- In the sidebar, go to
Serverless AI → Endpoints.
- In the endpoint list, next to the endpoint, click View logs. Alternatively, click
→ View logs.
View endpoint logs:
nebius ai endpoint logs $ENDPOINT_ID
Delete the endpoint
If you no longer need the endpoint, delete it. Once you delete the endpoint, you will not be charged for it.- Web console
- CLI
- Go SDK
- Python SDK
- JavaScript SDK
- REST API
- In the sidebar, go to
Serverless AI → Endpoints.
- In the endpoint list, find the endpoint and click
→ Delete.
- Confirm the endpoint deletion.
nebius ai endpoint delete $ENDPOINT_ID
Run the following code:In
deleteEndpointService := sdk.Services().Ai().V1().Endpoint()
deleteEndpointOperation, err := deleteEndpointService.Delete(
ctx,
&ai.DeleteEndpointRequest{Id: "<endpoint_ID>"},
)
if err != nil {
return fmt.Errorf("delete endpoint: %w", err)
}
if _, err = deleteEndpointOperation.Wait(ctx); err != nil {
return fmt.Errorf("wait for endpoint deletion: %w", err)
}
ai.DeleteEndpointRequest, set Id to the endpoint ID that you saved when you created the endpoint.Run the following code:In
delete_endpoint_service = EndpointServiceClient(sdk)
delete_endpoint_operation = await delete_endpoint_service.delete(
DeleteEndpointRequest(id="<endpoint_ID>"),
)
await delete_endpoint_operation.wait()
DeleteEndpointRequest, set id to the endpoint ID that you saved when you created the endpoint.Run the following code:In
const deleteEndpointService = new EndpointService(sdk);
const deleteEndpointOperation = await deleteEndpointService.delete(
DeleteEndpointRequest.create({ id: "<endpoint_ID>" }),
).result;
await deleteEndpointOperation.wait();
DeleteEndpointRequest, set id to the endpoint ID that you saved when you created the endpoint.Send the following request:In the request, specify:
curl --request DELETE \
--url "https://api.nebius.cloud/ai/v1/endpoints/<endpoint_ID>" \
--header "Authorization: Bearer <access_token>"
- Your access token in the
Authorizationheader. - In the request path, the endpoint ID returned in the
resourceIdparameter when you created the endpoint.
Expected results
- The endpoint is reachable over its managed HTTPS URL.
- A request without a token in the web console returns
200 OK. - A request without a token in the CLI, SDKs or REST API returns
401 Unauthorizedor403 Forbidden. - An endpoint can be deleted successfully.