執行個體

一個執行個體就是一項租下的報價，執行一個範本。這些端點做的事，跟 執行個體 頁面做的完全一樣。

部署執行個體

curl -s -X POST "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11",
    "template_id": "b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56",
    "disk_gb": 60,
    "label": "sft-run-14",
    "ssh_key_id": "7a3c1e08-42bd-4f19-9d63-5b8e0c2a1f40",
    "env_overrides": [
      {"key": "HF_TOKEN", "value": "hf_...", "secret": true}
    ]
  }'

欄位	型別	必填	備註
`offer_id`	uuid	是	必須仍是 `available`，否則呼叫會回傳 `409 OFFER_UNAVAILABLE`
`template_id`	uuid	是	系統範本、公開範本，或你的組織擁有的範本
`disk_gb`	整數	是	介於 10 與 20000 之間，且不得大於主機的 `machine.disk_gb`
`label`	字串，最多 64 個字元	否	會顯示在主控台清單中。預設為 `null`。
`ssh_key_id`	uuid	否	必須是持有該憑證者帳號上的金鑰。沒有它，執行個體上就沒有授權金鑰，你也就無法 SSH 進去。
`env_overrides`	`{key, value, secret}` 的陣列	否	依 key 比對，覆蓋在範本的 `env` 之上。值為 `null` 的項目會被捨棄。

環境變數覆寫會蓋在範本的 env 之上，但平台自己的覆蓋層又贏過這兩者。你無法蓋掉 JUPYTER_TOKEN 或 GPU_COUNT。

回應是 201 加上執行個體。計費從工作負載真正進入 running 時開始，不是在這個呼叫的當下。

部署一執行就會花錢

餘額是在部署時檢查，不是預留。執行個體執行期間，GPU 時間按秒計費；停止期間，硬碟按每 GB 每小時計費。餘額歸零時執行中的執行個體會被自動停止，到 −$5 時會被銷毀。請參閱計費如何運作。

執行個體欄位

{
  "id": "e08b5f27-1c4a-4d90-b3e6-72a9d1f45c83",
  "label": "sft-run-14",
  "status": "creating",
  "disk_gb": 60,
  "price_per_hour_microusd": 2290000,
  "storage_price_per_gb_hour_microusd": 250,
  "ssh_host": "sh-us-tx-01.ssh.superheat.dev",
  "ssh_port": 41207,
  "ssh_user": "root",
  "jupyter_url": null,
  "open_url": null,
  "created_at": "2026-07-24T11:12:03.771Z",
  "started_at": null,
  "status_changed_at": "2026-07-24T11:12:03.771Z",
  "destroyed_at": null,
  "spend_microusd": 0,
  "deployed_by": "you@example.com",
  "offer": { "id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11" },
  "template": { "id": "b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56" }
}

offer 與 template 是報價與範本中記載的完整物件；這裡只是縮略顯示。

欄位	型別	意義
`status`	字串	`creating`、`starting`、`running`、`stopping`、`stopped`、`destroying`、`destroyed`、`error` 其中之一。請參閱執行個體狀態。
`disk_gb`	整數	你要求的硬碟容量，停止期間按每 GB 每小時計費
`price_per_hour_microusd`	整數	租用當下從報價快照下來的費率，涵蓋整個切片
`storage_price_per_gb_hour_microusd`	整數	租用當下快照下來的硬碟費率
`ssh_host`, `ssh_port`, `ssh_user`	字串、整數、字串	連線目標。連接埠是從主機公開的範圍中指派的，永遠不會是 22。
`jupyter_url`	字串或 null	JupyterLab 進入點，在 `jupyter` 範本回報之後出現
`open_url`	字串或 null	範本的開啟按鈕端點，在它被回報之後出現
`created_at`, `started_at`, `status_changed_at`, `destroyed_at`	時間戳記	`started_at` 在工作負載第一次執行時設定
`spend_microusd`	整數	這個執行個體目前已結算的費用
`deployed_by`	字串	部署它的成員的電子郵件

列出執行個體

curl -s "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

回傳目前組織的 {"items": [...]}，最新的排前面。除非你帶上 include_destroyed=true，否則已銷毀的執行個體不會包含在內。

取得單一執行個體

curl -s "$SUPERHEAT_API/v1/instances/e08b5f27-1c4a-4d90-b3e6-72a9d1f45c83" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

未知的 id，以及屬於別的組織的執行個體，都會回傳 404 INSTANCE_NOT_FOUND。

停止、啟動與銷毀

請求	效果	可從哪些狀態執行
`POST /v1/instances/{id}/stop`	關閉容器，保留硬碟並保住 GPU 名額。狀態變成 `stopping`，接著是 `stopped`。	`running`
`POST /v1/instances/{id}/start`	用同一顆硬碟把已停止的執行個體叫回來。狀態變成 `starting`，接著是 `running`。	`stopped`
`DELETE /v1/instances/{id}`	拆掉執行個體並釋放切片。狀態變成 `destroying`，接著是 `destroyed`。	`running`, `stopped`, `error`

curl -s -X POST "$SUPERHEAT_API/v1/instances/$INSTANCE_ID/stop" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

這三個都會回傳處於新的過渡狀態的完整執行個體物件 —— 轉換是非同步完成的，所以請持續輪詢直到狀態穩定下來。

從不允許的狀態呼叫其中之一，會回傳 409 INVALID_STATE，訊息中會指出目前的狀態，例如 Cannot start an instance while it is running。啟動時也會重新檢查餘額，可能回傳 402 INSUFFICIENT_BALANCE。

銷毀會刪掉硬碟

DELETE 是不可逆的：容器、硬碟以及上面的所有東西都會消失，而報價會回到市集上。如果你希望資料還在那裡等你，請改用停止。請參閱停止與銷毀的差別。

日誌

curl -s "$SUPERHEAT_API/v1/instances/$INSTANCE_ID/logs?tail=50" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

{
  "lines": [
    "[2026-07-24 11:12:07] superheat-agent: pulling image vastai/pytorch",
    "[2026-07-24 11:12:11] superheat-agent: image ready, creating container",
    "[2026-07-24 11:12:13] nvidia-smi: detected 1 GPU(s), driver 570.86",
    "[2026-07-24 11:12:14] sshd: listening on 0.0.0.0:41207",
    "[2026-07-24 11:12:15] superheat-agent: instance is ready"
  ]
}

參數	範圍	預設
`tail`	1 到 1000	200

超出該範圍的值會被 422 拒絕。在工作負載第一次執行之前 lines 都是空的，所以處於 creating 的執行個體什麼都不會回傳。沒有串流端點；請輪詢這一個 —— 主控台每三秒重新整理一次。請參閱日誌。

從頭到尾：部署並連線

這是從一個空殼子到 SSH 工作階段的完整路徑。前提是你有 jq、已在主控台加入 SSH 金鑰，而且餘額裡有錢。

1. 設定你的憑證。 SSH 金鑰屬於你的帳號而不是組織，所以列出它們需要工作階段權杖；其他一切都用 API 金鑰跑。

export SUPERHEAT_API="https://<your-superheat-api-host>"
export SUPERHEAT_KEY="shk_your_key_here"
AUTH=(-H "Authorization: Bearer $SUPERHEAT_KEY")

2. 找出 SSH 金鑰 id，用已登入瀏覽器取得的工作階段權杖：

curl -s "$SUPERHEAT_API/v1/ssh-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  | jq -r '.items[] | "\(.id)  \(.name)  \(.fingerprint)"'

7a3c1e08-42bd-4f19-9d63-5b8e0c2a1f40  laptop  SHA256:Yx1r0oW2fS7Tq8kJ3mN4pB6vC9dE0gH2iK5lM8nP1qR

SSH_KEY_ID="7a3c1e08-42bd-4f19-9d63-5b8e0c2a1f40"

3. 挑最便宜的單張 H100 切片：

OFFER_ID=$(curl -s "$SUPERHEAT_API/v1/offers?gpu_model=H100%20SXM&num_gpus=1&sort=price_asc" \
  "${AUTH[@]}" | jq -r '.items[0].id')

4. 挑一個 SSH 範本：

TEMPLATE_ID=$(curl -s "$SUPERHEAT_API/v1/templates?tab=recommended&mode=ssh" \
  "${AUTH[@]}" | jq -r '.items[0].id')

5. 部署：

INSTANCE_ID=$(curl -s -X POST "$SUPERHEAT_API/v1/instances" \
  "${AUTH[@]}" -H "Content-Type: application/json" \
  -d "{\"offer_id\":\"$OFFER_ID\",\"template_id\":\"$TEMPLATE_ID\",\"disk_gb\":60,\"label\":\"api-demo\",\"ssh_key_id\":\"$SSH_KEY_ID\"}" \
  | jq -r '.id')

6. 等待進入 running：

while :; do
  STATUS=$(curl -s "$SUPERHEAT_API/v1/instances/$INSTANCE_ID" "${AUTH[@]}" | jq -r '.status')
  echo "$STATUS"
  case "$STATUS" in
    running) break ;;
    error|destroyed) exit 1 ;;
  esac
  sleep 3
done

7. 從執行個體本身組出連線指令，不要自己拼湊 —— 連接埠是每個執行個體各自指派的：

curl -s "$SUPERHEAT_API/v1/instances/$INSTANCE_ID" "${AUTH[@]}" \
  | jq -r '"ssh -p \(.ssh_port) \(.ssh_user)@\(.ssh_host)"'

ssh -p 41207 root@sh-us-tx-01.ssh.superheat.dev

8. 連線並檢查 GPU：

ssh -p 41207 root@sh-us-tx-01.ssh.superheat.dev nvidia-smi

9. 暫停時停止，做完時銷毀：

curl -s -X POST "$SUPERHEAT_API/v1/instances/$INSTANCE_ID/stop" "${AUTH[@]}" | jq -r '.status'
curl -s -X DELETE "$SUPERHEAT_API/v1/instances/$INSTANCE_ID" "${AUTH[@]}" | jq -r '.status'

部署執行個體​

執行個體欄位​

列出執行個體​

取得單一執行個體​

停止、啟動與銷毀​

日誌​

從頭到尾：部署並連線​