POST
/
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",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "vllm/vllm-openai:latest",
      "args": "--model mistralai/Mistral-7B-v0.1",
      "shared_memory_in_gb": 8,
      "envs": [
        {
          "name": "HUGGING_FACE_HUB_TOKEN",
          "value": "hugging_face_api_token"
        }
      ],
      "port_mappings": [
        {
          "host_port": 80,
          "container_port": 8000
        }
      ],
      "volume_mounts": [
        {
          "host_path": "~/.cache/huggingface",
          "container_path": "/root/.cache/huggingface"
        }
      ]
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "os": "ubuntu22.04_cuda12.2_shade_os",
  "volume_ids": [
    "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
  ],
  "ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
}'
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "cloud_assigned_id": "13b057d7-e266-4869-985f-760fe75a78b3"
}

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.

See the following tutorials related to instance creation:

Creating an Instance

Creating an Instance with a Running Container

Creating an Instance with a Startup Script

Authorizations

X-API-KEY
string
headerrequired

Body

application/json
cloud
enum<string>
required

Specifies the underlying cloud provider. See this explanation for more details.

Available options:
aws,
azure,
lambdalabs,
tensordock,
runpod,
latitude,
jarvislabs,
oblivus,
paperspace,
datacrunch,
massedcompute,
vultr
region
string
required

Specifies the region.

shade_instance_type
string
required

The Shadeform standardized instance type. See this explanation for more details.

shade_cloud
boolean
required

Specifies if the instance is launched in Shade Cloud or in a linked cloud account.

name
string
required

The name of the instance

launch_configuration
object

Defines automatic actions after the instance becomes active.

os
string

The operating system of the instance.

volume_ids
string[]

List of volume IDs to be mounted. Currently only supports 1 volume at a time.

ssh_key_id
string

The ID of the SSH Key.

Response

200 - application/json
id
string
required

The unique identifier for the instance. Used in the instances for the /instances/{id}/info and /instances/{id}/delete APIs.

cloud_assigned_id
string
required

The unique identifier of the instance issued by the underlying cloud provider.