API 總覽

主控台做的每一件事，都是靠呼叫這套 API 完成的。你可以從腳本瀏覽報價、部署執行個體、觀看它的日誌、把它停止再銷毀，背後是同一個組織、同一份餘額。

基礎 URL

所有端點都位於 Superheat API 主機上的 /v1 前綴之下。請求與回應都是 JSON。設定兩個變數，本節的範例就能照原樣執行：

export SUPERHEAT_API="https://<your-superheat-api-host>"
export SUPERHEAT_KEY="shk_your_key_here"

下面每一條路徑都是相對於該主機書寫的 —— /v1/offers 指的是 $SUPERHEAT_API/v1/offers。

API 涵蓋的範圍

範圍	端點	說明文件
健康檢查	`GET /v1/health`	本頁
型錄	`GET /v1/offers`, `GET /v1/offers/{id}`, `GET /v1/catalog/status`	報價
範本	`GET /v1/templates`, `GET /v1/templates/{id}`, `GET /v1/templates/by-hash/{hash_id}`, `POST /v1/templates/{id}/duplicate`	範本
執行個體	`POST /v1/instances`, `GET /v1/instances`, `GET /v1/instances/{id}`, `POST /v1/instances/{id}/stop`, `POST /v1/instances/{id}/start`, `DELETE /v1/instances/{id}`, `GET /v1/instances/{id}/logs`	執行個體
金鑰	`GET /v1/api-keys`, `POST /v1/api-keys`, `DELETE /v1/api-keys/{id}`	API 金鑰

API 不做的事

無法使用	改用這個方式
用 API 金鑰儲值餘額	結帳僅限管理員，會拒絕 API 金鑰。請在主控台的計費頁面儲值。
用 API 金鑰呼叫帳號端點	`/v1/me` 與 `/v1/ssh-keys` 需要已登入的工作階段。請先在主控台加入 SSH 金鑰，再把部署自動化。
串流日誌	輪詢 `GET /v1/instances/{id}/logs?tail=N`。主控台每三秒輪詢一次。
挑選機器、主機或放置位置	你租的是一項報價。由 Superheat 決定它在哪裡執行。
自己訂價	價格由 Superheat 訂定，並在你租用時快照到執行個體上。

金額欄位

名稱以 _microusd 結尾的欄位是整數，計算單位為百萬分之一美元。除以 1,000,000 就是美元：2290000 是每小時 $2.29，而 spend_microusd 為 410000 表示目前已花費 $0.41。

你的第一個請求

GET /v1/health 不需要憑證，所以這是確認你連得上 API 最快的方式：

curl -s -i "$SUPERHEAT_API/v1/health"

{
  "status": "ok",
  "version": "0.1.0",
  "commit": "9f2c1ab",
  "app_env": "production",
  "provisioner": "dispatch",
  "inventory_sync_enabled": true,
  "database": true
}

欄位	型別	意義
`status`	字串	`ok`，或在某項檢查失敗時為 `degraded`
`version`	字串	API 版本
`commit`	字串或 null	部署的這份 API 是從哪個 Git commit 建置的；非部署建置時為 `null`
`app_env`	字串	是哪個環境回應的，例如 `production`
`provisioner`	字串	真實硬體是 `dispatch`，假機群是 `simulated`
`inventory_sync_enabled`	布林值	型錄是否正在從實際存貨重新整理
`database`	布林值	剛剛是否真的有一個查詢往返資料庫

這個處理常式會對資料庫執行一次 SELECT 1，上限 3 秒，而不是回傳一個固定字面值。如果那次失敗，它會以同樣的主體形狀回 503，status 為 degraded、database 為 false——所以請看 HTTP 狀態碼，不要只看有沒有主體。那三個環境欄位存在的目的，是讓「一個 API 悄悄在服務模擬機群」這件事從外部就看得出來；provisioner 是 simulated 代表你部署出來的執行個體不是真的機器。

其他所有端點都需要 bearer token。先建立一把 API 金鑰（API 金鑰），然後列出最便宜的三項報價：

curl -s "$SUPERHEAT_API/v1/offers?sort=price_asc" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

{
  "items": [
    {
      "id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11",
      "gpu_model": "H100 SXM",
      "num_gpus": 1,
      "vram_gb": 80,
      "tflops": 198.0,
      "cuda_version": "12.8",
      "vm_capable": false,
      "disk_quota_capable": false,
      "price_per_hour_microusd": 2290000,
      "storage_price_per_gb_hour_microusd": 250,
      "max_duration_hours": null,
      "status": "available",
      "available_units": 3,
      "capacity_units": 8,
      "machine": {
        "hostname": "sh-us-tx-01",
        "region": "US-TX",
        "country_code": "US",
        "cpu_model": "Intel Xeon Platinum 8480+",
        "cpu_cores": 112,
        "ram_gb": 2048,
        "disk_type": "nvme",
        "disk_gb": 15000,
        "net_up_mbps": 8000,
        "net_down_mbps": 8000,
        "pcie_gen": 5,
        "pcie_width": 16,
        "reliability": 0.998,
        "verified": true,
        "next_maintenance": null
      }
    }
  ]
}

從這裡開始，執行個體會走完整條部署與連線的路徑。

組織範圍

每個物件都屬於某個組織，絕不會直接屬於某個使用者。沒有帶 X-Org-Id 標頭的請求會在你的個人組織下執行；API 金鑰則永遠在它被建立時所屬的組織下執行。請參閱驗證。

基礎 URL​

API 涵蓋的範圍​

API 不做的事​

金額欄位​

你的第一個請求​

組織範圍​