/instances/create
curl --request POST \
--url https://api.shadeform.ai/v1/instances/create \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"cloud": "hyperstack",
"region": "canada-1",
"shade_instance_type": "A6000",
"shade_cloud": true,
"name": "cool-gpu-server",
"os": "ubuntu22.04_cuda12.2_shade_os",
"template_id": "template-123",
"volume_ids": [
"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
],
"ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
"auto_delete": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"alert": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"volume_mount": {
"auto": true
},
"tags": [
"tag1"
],
"envs": [
{
"name": "HUGGING_FACE_HUB_TOKEN",
"value": "hugging_face_api_token"
}
]
}
'import requests
url = "https://api.shadeform.ai/v1/instances/create"
payload = {
"cloud": "hyperstack",
"region": "canada-1",
"shade_instance_type": "A6000",
"shade_cloud": True,
"name": "cool-gpu-server",
"os": "ubuntu22.04_cuda12.2_shade_os",
"template_id": "template-123",
"volume_ids": ["78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"],
"ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
"auto_delete": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"alert": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"volume_mount": { "auto": True },
"tags": ["tag1"],
"envs": [
{
"name": "HUGGING_FACE_HUB_TOKEN",
"value": "hugging_face_api_token"
}
]
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
cloud: 'hyperstack',
region: 'canada-1',
shade_instance_type: 'A6000',
shade_cloud: true,
name: 'cool-gpu-server',
os: 'ubuntu22.04_cuda12.2_shade_os',
template_id: 'template-123',
volume_ids: ['78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40'],
ssh_key_id: '78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40',
auto_delete: {date_threshold: '2006-01-02T15:04:05-07:00', spend_threshold: '3.14'},
alert: {date_threshold: '2006-01-02T15:04:05-07:00', spend_threshold: '3.14'},
volume_mount: {auto: true},
tags: ['tag1'],
envs: [{name: 'HUGGING_FACE_HUB_TOKEN', value: 'hugging_face_api_token'}]
})
};
fetch('https://api.shadeform.ai/v1/instances/create', 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.shadeform.ai/v1/instances/create",
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([
'cloud' => 'hyperstack',
'region' => 'canada-1',
'shade_instance_type' => 'A6000',
'shade_cloud' => true,
'name' => 'cool-gpu-server',
'os' => 'ubuntu22.04_cuda12.2_shade_os',
'template_id' => 'template-123',
'volume_ids' => [
'78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40'
],
'ssh_key_id' => '78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40',
'auto_delete' => [
'date_threshold' => '2006-01-02T15:04:05-07:00',
'spend_threshold' => '3.14'
],
'alert' => [
'date_threshold' => '2006-01-02T15:04:05-07:00',
'spend_threshold' => '3.14'
],
'volume_mount' => [
'auto' => true
],
'tags' => [
'tag1'
],
'envs' => [
[
'name' => 'HUGGING_FACE_HUB_TOKEN',
'value' => 'hugging_face_api_token'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$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.shadeform.ai/v1/instances/create"
payload := strings.NewReader("{\n \"cloud\": \"hyperstack\",\n \"region\": \"canada-1\",\n \"shade_instance_type\": \"A6000\",\n \"shade_cloud\": true,\n \"name\": \"cool-gpu-server\",\n \"os\": \"ubuntu22.04_cuda12.2_shade_os\",\n \"template_id\": \"template-123\",\n \"volume_ids\": [\n \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\"\n ],\n \"ssh_key_id\": \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\",\n \"auto_delete\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"alert\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"volume_mount\": {\n \"auto\": true\n },\n \"tags\": [\n \"tag1\"\n ],\n \"envs\": [\n {\n \"name\": \"HUGGING_FACE_HUB_TOKEN\",\n \"value\": \"hugging_face_api_token\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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.shadeform.ai/v1/instances/create")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cloud\": \"hyperstack\",\n \"region\": \"canada-1\",\n \"shade_instance_type\": \"A6000\",\n \"shade_cloud\": true,\n \"name\": \"cool-gpu-server\",\n \"os\": \"ubuntu22.04_cuda12.2_shade_os\",\n \"template_id\": \"template-123\",\n \"volume_ids\": [\n \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\"\n ],\n \"ssh_key_id\": \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\",\n \"auto_delete\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"alert\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"volume_mount\": {\n \"auto\": true\n },\n \"tags\": [\n \"tag1\"\n ],\n \"envs\": [\n {\n \"name\": \"HUGGING_FACE_HUB_TOKEN\",\n \"value\": \"hugging_face_api_token\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.shadeform.ai/v1/instances/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cloud\": \"hyperstack\",\n \"region\": \"canada-1\",\n \"shade_instance_type\": \"A6000\",\n \"shade_cloud\": true,\n \"name\": \"cool-gpu-server\",\n \"os\": \"ubuntu22.04_cuda12.2_shade_os\",\n \"template_id\": \"template-123\",\n \"volume_ids\": [\n \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\"\n ],\n \"ssh_key_id\": \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\",\n \"auto_delete\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"alert\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"volume_mount\": {\n \"auto\": true\n },\n \"tags\": [\n \"tag1\"\n ],\n \"envs\": [\n {\n \"name\": \"HUGGING_FACE_HUB_TOKEN\",\n \"value\": \"hugging_face_api_token\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}Instances
/instances/create
Create a new GPU instance. Our create API is designed to be asynchronous, so the response will be a CreateResponse object with a status of “creating”. We then have a process that will pick it up and create it. You can poll the /instances//info endpoint to check the status of the instance.
POST
/
instances
/
create
/instances/create
curl --request POST \
--url https://api.shadeform.ai/v1/instances/create \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"cloud": "hyperstack",
"region": "canada-1",
"shade_instance_type": "A6000",
"shade_cloud": true,
"name": "cool-gpu-server",
"os": "ubuntu22.04_cuda12.2_shade_os",
"template_id": "template-123",
"volume_ids": [
"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
],
"ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
"auto_delete": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"alert": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"volume_mount": {
"auto": true
},
"tags": [
"tag1"
],
"envs": [
{
"name": "HUGGING_FACE_HUB_TOKEN",
"value": "hugging_face_api_token"
}
]
}
'import requests
url = "https://api.shadeform.ai/v1/instances/create"
payload = {
"cloud": "hyperstack",
"region": "canada-1",
"shade_instance_type": "A6000",
"shade_cloud": True,
"name": "cool-gpu-server",
"os": "ubuntu22.04_cuda12.2_shade_os",
"template_id": "template-123",
"volume_ids": ["78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"],
"ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
"auto_delete": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"alert": {
"date_threshold": "2006-01-02T15:04:05-07:00",
"spend_threshold": "3.14"
},
"volume_mount": { "auto": True },
"tags": ["tag1"],
"envs": [
{
"name": "HUGGING_FACE_HUB_TOKEN",
"value": "hugging_face_api_token"
}
]
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
cloud: 'hyperstack',
region: 'canada-1',
shade_instance_type: 'A6000',
shade_cloud: true,
name: 'cool-gpu-server',
os: 'ubuntu22.04_cuda12.2_shade_os',
template_id: 'template-123',
volume_ids: ['78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40'],
ssh_key_id: '78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40',
auto_delete: {date_threshold: '2006-01-02T15:04:05-07:00', spend_threshold: '3.14'},
alert: {date_threshold: '2006-01-02T15:04:05-07:00', spend_threshold: '3.14'},
volume_mount: {auto: true},
tags: ['tag1'],
envs: [{name: 'HUGGING_FACE_HUB_TOKEN', value: 'hugging_face_api_token'}]
})
};
fetch('https://api.shadeform.ai/v1/instances/create', 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.shadeform.ai/v1/instances/create",
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([
'cloud' => 'hyperstack',
'region' => 'canada-1',
'shade_instance_type' => 'A6000',
'shade_cloud' => true,
'name' => 'cool-gpu-server',
'os' => 'ubuntu22.04_cuda12.2_shade_os',
'template_id' => 'template-123',
'volume_ids' => [
'78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40'
],
'ssh_key_id' => '78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40',
'auto_delete' => [
'date_threshold' => '2006-01-02T15:04:05-07:00',
'spend_threshold' => '3.14'
],
'alert' => [
'date_threshold' => '2006-01-02T15:04:05-07:00',
'spend_threshold' => '3.14'
],
'volume_mount' => [
'auto' => true
],
'tags' => [
'tag1'
],
'envs' => [
[
'name' => 'HUGGING_FACE_HUB_TOKEN',
'value' => 'hugging_face_api_token'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$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.shadeform.ai/v1/instances/create"
payload := strings.NewReader("{\n \"cloud\": \"hyperstack\",\n \"region\": \"canada-1\",\n \"shade_instance_type\": \"A6000\",\n \"shade_cloud\": true,\n \"name\": \"cool-gpu-server\",\n \"os\": \"ubuntu22.04_cuda12.2_shade_os\",\n \"template_id\": \"template-123\",\n \"volume_ids\": [\n \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\"\n ],\n \"ssh_key_id\": \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\",\n \"auto_delete\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"alert\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"volume_mount\": {\n \"auto\": true\n },\n \"tags\": [\n \"tag1\"\n ],\n \"envs\": [\n {\n \"name\": \"HUGGING_FACE_HUB_TOKEN\",\n \"value\": \"hugging_face_api_token\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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.shadeform.ai/v1/instances/create")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cloud\": \"hyperstack\",\n \"region\": \"canada-1\",\n \"shade_instance_type\": \"A6000\",\n \"shade_cloud\": true,\n \"name\": \"cool-gpu-server\",\n \"os\": \"ubuntu22.04_cuda12.2_shade_os\",\n \"template_id\": \"template-123\",\n \"volume_ids\": [\n \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\"\n ],\n \"ssh_key_id\": \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\",\n \"auto_delete\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"alert\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"volume_mount\": {\n \"auto\": true\n },\n \"tags\": [\n \"tag1\"\n ],\n \"envs\": [\n {\n \"name\": \"HUGGING_FACE_HUB_TOKEN\",\n \"value\": \"hugging_face_api_token\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.shadeform.ai/v1/instances/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cloud\": \"hyperstack\",\n \"region\": \"canada-1\",\n \"shade_instance_type\": \"A6000\",\n \"shade_cloud\": true,\n \"name\": \"cool-gpu-server\",\n \"os\": \"ubuntu22.04_cuda12.2_shade_os\",\n \"template_id\": \"template-123\",\n \"volume_ids\": [\n \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\"\n ],\n \"ssh_key_id\": \"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40\",\n \"auto_delete\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"alert\": {\n \"date_threshold\": \"2006-01-02T15:04:05-07:00\",\n \"spend_threshold\": \"3.14\"\n },\n \"volume_mount\": {\n \"auto\": true\n },\n \"tags\": [\n \"tag1\"\n ],\n \"envs\": [\n {\n \"name\": \"HUGGING_FACE_HUB_TOKEN\",\n \"value\": \"hugging_face_api_token\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}The example in the right sidebar is a schema only and will not work out of the box. Only ‘docker_configuration’ or ‘script_configuration’ can be specified but not both.
Creating an Instance
Creating an Instance with a Running Container
Creating an Instance with a Startup Script
Authorizations
Body
application/json
Specifies the underlying cloud provider. See this explanation for more details.
Example:
"hyperstack"
Specifies the region.
Example:
"canada-1"
The Shadeform standardized instance type. See this explanation for more details.
Example:
"A6000"
Specifies if the instance is launched in Shade Cloud or in a linked cloud account.
Example:
true
The name of the instance
Example:
"cool-gpu-server"
The operating system of the instance.
Example:
"ubuntu22.04_cuda12.2_shade_os"
The ID of the template to use for this instance
Example:
"template-123"
Defines automatic actions after the instance becomes active.
Show child attributes
Show child attributes
List of volume IDs to be mounted. Currently only supports 1 volume at a time.
The ID of the storage volume.
The ID of the SSH Key.
Example:
"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
Set a date or spend threshold to automatically delete the instance
Show child attributes
Show child attributes
Set a date or spend threshold to receive an email alert
Show child attributes
Show child attributes
Settings for mounting volumes onto file systems
Show child attributes
Show child attributes
Add custom, searchable tags to instances.
Tag for searching and grouping
List of environment variable name and values to automatically add to the instance
Show child attributes
Show child attributes
Response
200 - application/json
Returns a CreateResponse object
Response of the /instances/create API call
The unique identifier for the instance. Used in the instances for the /instances/{id}/info and /instances/{id}/delete APIs.
Example:
"d290f1ee-6c54-4b01-90e6-d701748f0851"
⌘I