Skip to main content
POST
/
gpus
/
v2
/
instances
Create Instance
curl --request POST \
  --url https://api.novita.ai/gpus/v2/instances \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "example-instance",
  "product_id": "product-id",
  "image": "registry.example.com/namespace/image:tag",
  "billing": {
    "mode": "prepaid",
    "prepaid": {
      "months": 1,
      "auto_renew": {
        "enabled": true,
        "months": 1
      }
    }
  },
  "resource": {
    "rootfs_size_gb": 20,
    "gpu_num": 1,
    "min_cuda_version": ""
  },
  "registry_auth_id": "registry-auth-id",
  "entrypoint": "",
  "command": "",
  "envs": [
    {
      "key": "ENV_NAME",
      "value": "ENV_VALUE"
    }
  ],
  "ports": [
    {
      "port": 8080,
      "protocol": "tcp"
    }
  ],
  "network": {
    "id": "vpc-550e8400-e29b-41d4-a716-446655440000",
    "ip": "10.2.1.1"
  },
  "volumes": [
    {
      "type": "network",
      "id": "network-storage-id",
      "mount_point": "/data"
    }
  ],
  "candidate_regions": [
    "region-id"
  ],
  "tools": {
    "jupyter": {
      "enabled": true,
      "port": 8888,
      "protocol": "http"
    }
  },
  "auto_migrate": {
    "enabled": false,
    "include_system_disk": false
  }
}
'
import requests

url = "https://api.novita.ai/gpus/v2/instances"

payload = {
    "name": "example-instance",
    "product_id": "product-id",
    "image": "registry.example.com/namespace/image:tag",
    "billing": {
        "mode": "prepaid",
        "prepaid": {
            "months": 1,
            "auto_renew": {
                "enabled": True,
                "months": 1
            }
        }
    },
    "resource": {
        "rootfs_size_gb": 20,
        "gpu_num": 1,
        "min_cuda_version": ""
    },
    "registry_auth_id": "registry-auth-id",
    "entrypoint": "",
    "command": "",
    "envs": [
        {
            "key": "ENV_NAME",
            "value": "ENV_VALUE"
        }
    ],
    "ports": [
        {
            "port": 8080,
            "protocol": "tcp"
        }
    ],
    "network": {
        "id": "vpc-550e8400-e29b-41d4-a716-446655440000",
        "ip": "10.2.1.1"
    },
    "volumes": [
        {
            "type": "network",
            "id": "network-storage-id",
            "mount_point": "/data"
        }
    ],
    "candidate_regions": ["region-id"],
    "tools": { "jupyter": {
            "enabled": True,
            "port": 8888,
            "protocol": "http"
        } },
    "auto_migrate": {
        "enabled": False,
        "include_system_disk": False
    }
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "<authorization>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'},
  body: JSON.stringify({
    name: 'example-instance',
    product_id: 'product-id',
    image: 'registry.example.com/namespace/image:tag',
    billing: {mode: 'prepaid', prepaid: {months: 1, auto_renew: {enabled: true, months: 1}}},
    resource: {rootfs_size_gb: 20, gpu_num: 1, min_cuda_version: ''},
    registry_auth_id: 'registry-auth-id',
    entrypoint: '',
    command: '',
    envs: [{key: 'ENV_NAME', value: 'ENV_VALUE'}],
    ports: [{port: 8080, protocol: 'tcp'}],
    network: {id: 'vpc-550e8400-e29b-41d4-a716-446655440000', ip: '10.2.1.1'},
    volumes: [{type: 'network', id: 'network-storage-id', mount_point: '/data'}],
    candidate_regions: ['region-id'],
    tools: {jupyter: {enabled: true, port: 8888, protocol: 'http'}},
    auto_migrate: {enabled: false, include_system_disk: false}
  })
};

fetch('https://api.novita.ai/gpus/v2/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novita.ai/gpus/v2/instances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'example-instance',
    'product_id' => 'product-id',
    'image' => 'registry.example.com/namespace/image:tag',
    'billing' => [
        'mode' => 'prepaid',
        'prepaid' => [
                'months' => 1,
                'auto_renew' => [
                                'enabled' => true,
                                'months' => 1
                ]
        ]
    ],
    'resource' => [
        'rootfs_size_gb' => 20,
        'gpu_num' => 1,
        'min_cuda_version' => ''
    ],
    'registry_auth_id' => 'registry-auth-id',
    'entrypoint' => '',
    'command' => '',
    'envs' => [
        [
                'key' => 'ENV_NAME',
                'value' => 'ENV_VALUE'
        ]
    ],
    'ports' => [
        [
                'port' => 8080,
                'protocol' => 'tcp'
        ]
    ],
    'network' => [
        'id' => 'vpc-550e8400-e29b-41d4-a716-446655440000',
        'ip' => '10.2.1.1'
    ],
    'volumes' => [
        [
                'type' => 'network',
                'id' => 'network-storage-id',
                'mount_point' => '/data'
        ]
    ],
    'candidate_regions' => [
        'region-id'
    ],
    'tools' => [
        'jupyter' => [
                'enabled' => true,
                'port' => 8888,
                'protocol' => 'http'
        ]
    ],
    'auto_migrate' => [
        'enabled' => false,
        'include_system_disk' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novita.ai/gpus/v2/instances"

	payload := strings.NewReader("{\n  \"name\": \"example-instance\",\n  \"product_id\": \"product-id\",\n  \"image\": \"registry.example.com/namespace/image:tag\",\n  \"billing\": {\n    \"mode\": \"prepaid\",\n    \"prepaid\": {\n      \"months\": 1,\n      \"auto_renew\": {\n        \"enabled\": true,\n        \"months\": 1\n      }\n    }\n  },\n  \"resource\": {\n    \"rootfs_size_gb\": 20,\n    \"gpu_num\": 1,\n    \"min_cuda_version\": \"\"\n  },\n  \"registry_auth_id\": \"registry-auth-id\",\n  \"entrypoint\": \"\",\n  \"command\": \"\",\n  \"envs\": [\n    {\n      \"key\": \"ENV_NAME\",\n      \"value\": \"ENV_VALUE\"\n    }\n  ],\n  \"ports\": [\n    {\n      \"port\": 8080,\n      \"protocol\": \"tcp\"\n    }\n  ],\n  \"network\": {\n    \"id\": \"vpc-550e8400-e29b-41d4-a716-446655440000\",\n    \"ip\": \"10.2.1.1\"\n  },\n  \"volumes\": [\n    {\n      \"type\": \"network\",\n      \"id\": \"network-storage-id\",\n      \"mount_point\": \"/data\"\n    }\n  ],\n  \"candidate_regions\": [\n    \"region-id\"\n  ],\n  \"tools\": {\n    \"jupyter\": {\n      \"enabled\": true,\n      \"port\": 8888,\n      \"protocol\": \"http\"\n    }\n  },\n  \"auto_migrate\": {\n    \"enabled\": false,\n    \"include_system_disk\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.novita.ai/gpus/v2/instances")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "<authorization>")
  .body("{\n  \"name\": \"example-instance\",\n  \"product_id\": \"product-id\",\n  \"image\": \"registry.example.com/namespace/image:tag\",\n  \"billing\": {\n    \"mode\": \"prepaid\",\n    \"prepaid\": {\n      \"months\": 1,\n      \"auto_renew\": {\n        \"enabled\": true,\n        \"months\": 1\n      }\n    }\n  },\n  \"resource\": {\n    \"rootfs_size_gb\": 20,\n    \"gpu_num\": 1,\n    \"min_cuda_version\": \"\"\n  },\n  \"registry_auth_id\": \"registry-auth-id\",\n  \"entrypoint\": \"\",\n  \"command\": \"\",\n  \"envs\": [\n    {\n      \"key\": \"ENV_NAME\",\n      \"value\": \"ENV_VALUE\"\n    }\n  ],\n  \"ports\": [\n    {\n      \"port\": 8080,\n      \"protocol\": \"tcp\"\n    }\n  ],\n  \"network\": {\n    \"id\": \"vpc-550e8400-e29b-41d4-a716-446655440000\",\n    \"ip\": \"10.2.1.1\"\n  },\n  \"volumes\": [\n    {\n      \"type\": \"network\",\n      \"id\": \"network-storage-id\",\n      \"mount_point\": \"/data\"\n    }\n  ],\n  \"candidate_regions\": [\n    \"region-id\"\n  ],\n  \"tools\": {\n    \"jupyter\": {\n      \"enabled\": true,\n      \"port\": 8888,\n      \"protocol\": \"http\"\n    }\n  },\n  \"auto_migrate\": {\n    \"enabled\": false,\n    \"include_system_disk\": false\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.novita.ai/gpus/v2/instances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = '<authorization>'
request.body = "{\n  \"name\": \"example-instance\",\n  \"product_id\": \"product-id\",\n  \"image\": \"registry.example.com/namespace/image:tag\",\n  \"billing\": {\n    \"mode\": \"prepaid\",\n    \"prepaid\": {\n      \"months\": 1,\n      \"auto_renew\": {\n        \"enabled\": true,\n        \"months\": 1\n      }\n    }\n  },\n  \"resource\": {\n    \"rootfs_size_gb\": 20,\n    \"gpu_num\": 1,\n    \"min_cuda_version\": \"\"\n  },\n  \"registry_auth_id\": \"registry-auth-id\",\n  \"entrypoint\": \"\",\n  \"command\": \"\",\n  \"envs\": [\n    {\n      \"key\": \"ENV_NAME\",\n      \"value\": \"ENV_VALUE\"\n    }\n  ],\n  \"ports\": [\n    {\n      \"port\": 8080,\n      \"protocol\": \"tcp\"\n    }\n  ],\n  \"network\": {\n    \"id\": \"vpc-550e8400-e29b-41d4-a716-446655440000\",\n    \"ip\": \"10.2.1.1\"\n  },\n  \"volumes\": [\n    {\n      \"type\": \"network\",\n      \"id\": \"network-storage-id\",\n      \"mount_point\": \"/data\"\n    }\n  ],\n  \"candidate_regions\": [\n    \"region-id\"\n  ],\n  \"tools\": {\n    \"jupyter\": {\n      \"enabled\": true,\n      \"port\": 8888,\n      \"protocol\": \"http\"\n    }\n  },\n  \"auto_migrate\": {\n    \"enabled\": false,\n    \"include_system_disk\": false\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "id": "ca338f12f3"
}

Headers

​
Content-Type
string
required

Allowed value: application/json.

​
Authorization
string
required

Bearer authentication format, e.g.: Bearer {{API_KEY}}.

Body

application/json
​
name
string
required

Instance name. String, length: 1-255 characters.

Example:

"example-instance"

​
product_id
string
required

Product ID.

Example:

"product-id"

​
image
string
required

Image address. String, length: 1-500 characters.

Example:

"registry.example.com/namespace/image:tag"

​
billing
object
required

Billing configuration.

​
resource
object
required

Resource configuration.

​
type
enum<string>

Instance type. Allowed values: gpu, cpu. Default: gpu.

Available options:
gpu,
cpu
​
registry_auth_id
string

Saved registry authentication ID. String, length: 0-255 characters.

Example:

"registry-auth-id"

​
entrypoint
string

Container entrypoint.

Example:

""

​
command
string

Container startup command.

Example:

""

​
envs
object[]

Environment variable list.

​
ports
object[]

Exposed port list.

​
network
object

VPC network configuration.

​
volumes
object[]

Data disk / network storage mounts.

​
candidate_regions
string[]

Candidate regions for scheduling. The instance is finally scheduled to one of them.

Example:
["region-id"]
​
tools
object

Instance tool configuration. Currently only Jupyter is supported.

​
auto_migrate
object

Auto-migrate configuration.

Response

200 - application/json

OK

​
id
string

ID of the created instance

Example:

"ca338f12f3"

Last modified on June 23, 2026