Create Compute Instance

Creates a new compute instance with the specified configuration and SSH key.

Requirements:

Requires compute permissions (extra_permissions.compute = true)
Authentication required via admin API key
Valid SSH public key required for instance access

Key Features:

Create high-performance GPU instances
Specify sector for InfiniBand configuration (8x H100 only)
SSH key-based authentication
Automatic instance provisioning and region assignment
Idempotent creation with Idempotency-Key header (optional but recommended)

Common Use Cases:

Spin up compute resources for ML training
Create GPU instances for inference workloads
Set up development environments with H100 GPUs
Deploy distributed training with InfiniBand networking

Instance Types:

gpu_8x_h100_sxm5: 8x NVIDIA H100 GPUs (high-performance, supports sector configuration for InfiniBand)
gpu_1x_h100_sxm5: 1x NVIDIA H100 GPU (standard)

Idempotency:

Optional Idempotency-Key header prevents duplicate instance creation on retries
Responses cached for 10 minutes per unique key

See fal.ai docs for more details.

POST

compute

instances

Create Compute Instance

curl --request POST \
  --url https://api.fal.ai/v1/compute/instances \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "instance_type": "gpu_8x_h100_sxm5",
  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host"
}
'

import requests

url = "https://api.fal.ai/v1/compute/instances"

payload = {
    "instance_type": "gpu_8x_h100_sxm5",
    "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instance_type: 'gpu_8x_h100_sxm5',
    ssh_key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host'
  })
};

fetch('https://api.fal.ai/v1/compute/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "inst_abc123xyz",
  "instance_type": "gpu_8x_h100_sxm5",
  "region": "us-west",
  "sector": "sector_1",
  "status": "provisioning",
  "creator_user_nickname": "developer"
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Admin API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_ADMIN_API_KEY

Headers

Idempotency-Key

string

Optional idempotency key for safe request retries

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Request body for creating a new compute instance with SSH access

instance_type

enum<string>

required

Type of compute instance to create

Available options:

gpu_8x_h100_sxm5,

gpu_1x_h100_sxm5

Example:

"gpu_1x_h100_sxm5"

ssh_key

string

required

SSH public key for accessing the instance (e.g., 'ssh-rsa AAAAB3...')

Minimum string length: 1

Example:

"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC... user@host"

sector

enum<string>

Sector for InfiniBand configuration (only valid with gpu_8x_h100_sxm5)

Available options:

sector_1,

sector_2,

sector_3

Example:

"sector_1"

Response

Compute instance created successfully

Compute instance details including configuration, location, and status

string

required

Unique identifier for the compute instance

Example:

"inst_abc123xyz"

instance_type

enum<string>

required

Type of compute instance (GPU configuration)

Available options:

gpu_8x_h100_sxm5,

gpu_1x_h100_sxm5

Example:

"gpu_1x_h100_sxm5"

region

enum<string>

required

Geographical region where the instance is located

Available options:

us-west,

us-central,

us-east,

eu-north,

eu-west,

other

Example:

"us-west"

status

enum<string>

required

Current operational status of the instance

Available options:

ready,

init,

pending,

provisioning,

stopped,

unknown

Example:

"ready"

sector

enum<string>

Sector identifier for instance placement within the region (if applicable)

Available options:

sector_1,

sector_2,

sector_3

Example:

"sector_1"

string

IP address of the instance (available when instance is ready)

Example:

"203.0.113.42"

creator_user_nickname

string

Nickname of the user who created this instance

Example:

"developer"

Delete Compute InstanceDeletes a specific compute instance by its ID. This action is irreversible. **Requirements:** - Requires compute permissions (extra_permissions.compute = true) - Authentication required via admin API key - Instance must belong to the authenticated user's workspace **Key Features:** - Permanently remove compute instances - Free up compute resources - Stop billing for the instance - Clean up unused resources **Important:** - This action cannot be undone - All data on the instance will be lost - Instance will be immediately terminated - Billing stops after deletion **Common Use Cases:** - Clean up completed workloads - Remove failed or stuck instances - Manage compute costs - Free up quota for new instances See [fal.ai docs](https://docs.fal.ai/compute) for more details.

⌘I

Create Compute Instance

curl --request POST \
  --url https://api.fal.ai/v1/compute/instances \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "instance_type": "gpu_8x_h100_sxm5",
  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host"
}
'

import requests

url = "https://api.fal.ai/v1/compute/instances"

payload = {
    "instance_type": "gpu_8x_h100_sxm5",
    "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    instance_type: 'gpu_8x_h100_sxm5',
    ssh_key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7Kl4... user@host'
  })
};

fetch('https://api.fal.ai/v1/compute/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "inst_abc123xyz",
  "instance_type": "gpu_8x_h100_sxm5",
  "region": "us-west",
  "sector": "sector_1",
  "status": "provisioning",
  "creator_user_nickname": "developer"
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}