Sign in

v1

latestOpenAPI 3.0.02026-07-13288558.3 KB

/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/{id}/info endpoint to check the status of the instance.

post/instances/create

Request body

cloudstring required

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

regionstring required

Specifies the region.

shade_instance_typestring required

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

shade_cloudboolean required

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

namestring required

The name of the instance

osstring

The operating system of the instance.

template_idstring

The ID of the template to use for this instance

volume_idsVolumeID[]

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

ssh_key_idstring

The ID of the SSH Key.

tagsTag[]

Add custom, searchable tags to instances.

Example request

{
  "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",
  "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"
        }
      ],
      "registry_credentials": {
        "username": "username",
        "password": "password"
      }
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "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"
  },
  "tags": [
    "tag1"
  ],
  "envs": [
    {
      "name": "HUGGING_FACE_HUB_TOKEN",
      "value": "hugging_face_api_token"
    }
  ]
}

Response

Returns a CreateResponse object

idstring uuid required

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

Example response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}