報價

報價是一台機器上可租用的切片：1、2、4 或 8 張 GPU，價格是整個切片的價格。租用 GPU 頁面就是建構在這三個端點之上。概念請參閱報價與切片。

列出報價

curl -s "$SUPERHEAT_API/v1/offers?gpu_model=H100%20SXM&num_gpus=2&sort=price_asc" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

GET /v1/offers 回傳 {"items": [...]}。不帶任何查詢參數時，你會拿到所有可用的報價，最便宜的排前面。

篩選條件

參數	型別	預設	比對什麼
`gpu_model`	字串	無	完全相符的 GPU 型號，例如 `H100 SXM` 或 `H200 SXM`。區分大小寫與空白。
`num_gpus`	整數	無	切片大小：`1`、`2`、`4` 或 `8`
`region`	字串	無	區域代碼，例如 `US-CA`，或國家代碼，例如 `US`
`min_vram_gb`	整數	無	每張 GPU 至少有這麼多 VRAM 的報價
`max_price_per_hour_microusd`	整數	無	整個切片每小時價格等於或低於此值的報價，單位為百萬分之一美元：`$3.00` 就是 `3000000`
`include_rented`	布林值	`false`	設為 `true` 時，售罄的報價（`available_units` 為 `0`）會與仍有餘量的一起回傳。已下架的報價永遠不會回傳
`sort`	列舉	`price_asc`	見下方

篩選條件以 AND 結合。未知的 sort 值會被 422 拒絕。

排序值

值	排序依據
`price_asc`	切片每小時價格，最便宜的排前面
`price_desc`	切片每小時價格，最貴的排前面
`tflops_desc`	切片吞吐量，最高的排前面
`vram_desc`	每張 GPU 的 VRAM，最高的排前面

回應欄位

欄位	型別	意義
`id`	uuid	部署時把這個當作 `offer_id` 傳入
`gpu_model`	字串	切片中的 GPU 型號
`num_gpus`	整數	切片中的 GPU 數量
`available_units`	整數	這台機器目前還能提供多少則該形態。`0` 表示售罄，而不是已下架
`capacity_units`	整數	上限：機器完全閒置時能提供多少則
`vram_gb`	整數	每張 GPU 的 VRAM
`tflops`	浮點數	整個切片的吞吐量
`cuda_version`	字串	主機提供的 CUDA 版本
`vm_capable`	布林值	`vm` 啟動模式的範本能否在此執行
`disk_quota_capable`	布林值	主機是否強制執行每個執行個體的硬碟配額。見下文
`price_per_hour_microusd`	整數	整個切片每小時的價格
`storage_price_per_gb_hour_microusd`	整數	硬碟每 GB 每小時的價格
`max_duration_hours`	整數或 null	租用時間上限，若該報價有設定的話
`status`	字串	API 回傳的東西一律是 `available`。見下文
`machine`	物件	切片所在的主機

status 講的是「有沒有上架」，不是「有沒有被拿走」。唯一的另一個值是 inactive，代表該報價已下架——機器不在了、GPU 型號變了，或已經沒有任何定價規則對得上它——而已下架的報價會被從清單中過濾掉，在明細端點上回 404。售罄是 available_units 為 0。沒有 rented 這個狀態：一台 2 GPU 的機器會把它的 1x 形態賣兩次，所以同一個形態可以既被租走、又同時仍然可租。

disk_quota_capable 說的是這台機器能不能把你限制在你要求的 disk_gb 之內。無論如何，你都是按那個數字計費的。只有在主機把 Docker 的儲存放到啟用專案配額的 XFS 上時它才是 true，而那是機器擁有者要自己選擇做的一步，所以 false 很常見。在 false 的機器上，租這台機器的每個人共用同一個磁碟區，而一個寫超過自己所買容量的同居租用者可以把它塞爆；disk_gb 是型錄賣給你的一個上限，不是為你保留的份額。在 true 的機器上，它是逐執行個體強制執行的配額。主控台在報價卡片上會把這件事顯示成 guaranteed 或 shared。

machine 物件帶有 hostname、region、country_code、cpu_model、cpu_cores、ram_gb、disk_type、disk_gb、net_up_mbps、net_down_mbps、pcie_gen、pcie_width、reliability、verified 與 next_maintenance。

machine.disk_gb 是整個磁碟區，它是你部署時能要求的 disk_gb 的上界，不是「你一定拿得到」的承諾：其中 50 GB 保留給主機自己，而那台機器上其他租用者已經佔用的部分也要從剩下的扣掉。要得比剩下的多，會回 409 MACHINE_DISK_EXHAUSTED，並附上實際還有多少。

machine.reliability 在該主機從未被量測過時是 null，那跟 0.0 不是同一個宣稱。machine.next_maintenance 是主機排定讓這台機器下線的時間，或是 null。它取的是最早一個尚未開始、或仍在進行中的視窗的開始時間，所以它可能落在過去。請把它當成警示而不是保證——主機可以在你租下這台機器的一分鐘後才排一個視窗，而一個大約 75 分鐘之內就要開始的視窗，會讓部署以 409 MACHINE_IN_MAINTENANCE 失敗。

價格由 Superheat 訂定，不是機器擁有者，而報價上的價格會在你租用時快照到執行個體上。之後型錄價格變動，不會改變你正在付的費率。

取得單一報價

curl -s "$SUPERHEAT_API/v1/offers/5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

以上述格式回傳單一報價，售罄與否都一樣。未知與已下架的報價會回傳 404 OFFER_NOT_FOUND。

部署前請重新讀 available_units，不是 status。最後一個空閒單位有可能在你列出清單到你發出建立呼叫之間被拿走，而 POST /v1/instances 會回應 409 OFFER_UNAVAILABLE。

型錄新鮮度

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

{
  "last_synced_at": "2026-07-24T11:04:12.907Z",
  "last_error": null,
  "sync_enabled": true,
  "unpriced_gpu_models": []
}

欄位	型別	意義
`last_synced_at`	時間戳記或 null	型錄上次成功重新整理的時間
`last_error`	字串或 null	上一次重新整理的失敗原因，若有的話
`sync_enabled`	布林值	型錄究竟會不會自動重新整理
`unpriced_gpu_models`	字串陣列	上一次重新整理因為 Superheat 沒有它們的價格而扣住的 GPU 型號

重新整理失敗時會保留先前的型錄，而不是把它清空，所以 last_synced_at 很舊就表示你讀到的報價可能已經租不到了。這種情況下市集會顯示過期橫幅；在腳本裡，請把過期的時間戳記當成預期會出現 409 OFFER_UNAVAILABLE 的理由，並改用下一項報價重試。

在 unpriced_gpu_models 裡的型號完全不會產生報價，而不是用一個編出來的價格上架，所以光看 /v1/offers，那種硬體跟根本沒人在託管的硬體是分不出來的。這個欄位是唯一能區分兩者的方式：如果你要找的型號列在這裡，代表容量存在但還不能租，而一直輪詢 /v1/offers 找它永遠不會成功。

列出報價​

篩選條件​

排序值​

回應欄位​

取得單一報價​

型錄新鮮度​

列出報價

篩選條件

排序值

回應欄位

取得單一報價

型錄新鮮度