報價

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

列出報價

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

GET /v1/offers 回傳 {"items": [...], "next_cursor": ...}。篩選、排序與分頁全都在伺服器端完成。不帶任何查詢參數時，你會拿到所有可用的報價，最便宜的排前面，數量以分頁中說明的不分頁上限為準。

篩選條件

參數	型別	預設	比對什麼
`gpu_model`	字串	無	完全相符的 GPU 型號，例如 `H100 SXM` 或 `H200 SXM`。區分大小寫與空白。
`gpu_family`	字串	無	架構系列：`Hopper`、`Ampere`、`Ada`、`Blackwell` 或 `Other`。系列由伺服器依正規化後的型號名稱判定，所以像 `NVIDIA GeForce RTX 4090` 這樣的原始名稱也會歸入 `Ada`。型錄中目前有哪些系列、各有多少報價，請見型錄摘要。沒有任何上架報價的系列會回傳空頁，而不是錯誤
`q`	字串，最多 100 個字元	無	自由文字搜尋：在 GPU 型號、主機名稱與區域串在一起的文字中做不區分大小寫的子字串比對。`%` 與 `_` 按字面比對，不是萬用字元
`num_gpus`	整數	無	切片大小：`1`、`2`、`4` 或 `8`
`region`	字串	無	區域代碼，例如 `US-CA`，或國家代碼，例如 `US`
`min_vram_gb`	整數	無	每張 GPU 至少有這麼多 VRAM 的報價
`max_price_per_hour_micro`	整數	無	整個切片每小時價格等於或低於此值的報價，單位為百萬分之一美元：`$3.00` 就是 `3000000`
`include_rented`	布林值	`false`	設為 `true` 時，售罄的報價（`available_units` 為 `0`）會與仍有餘量的一起回傳。已下架的報價永遠不會回傳
`sort`	列舉	`price_asc`	見下方
`limit`	整數，1 到 200	無	每頁筆數。見分頁
`cursor`	字串	無	上一頁的 `next_cursor`

篩選條件以 AND 結合。未知的 sort 值、超出 1 到 200 的 limit，或超出欄位範圍的數字，會被 422 拒絕。

排序值

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

排序值相同的報價依 id 排列，所以兩次請求之間的順序是穩定的。

分頁

傳入 limit 即可分頁。每個回應都帶有 next_cursor；把它當作 cursor 傳回，並使用同一個 sort，就能取得下一頁。最後一頁的 next_cursor 為 null。

curl -s "$SUPERHEAT_API/v1/offers?sort=price_asc&limit=100&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

游標是排序中的一個位置，而不是一份快照：它記錄的是上一頁最後一筆報價的排序值與 id。你逐頁讀取期間新上架的報價會落在它排序所在的位置，不會擠動後面的頁。兩頁之間可以變更篩選條件。
游標只對簽發它的那種排序有效。來自另一種排序或被改動過的游標，會被 422 INVALID_CURSOR 拒絕。拿掉游標從頭開始即可。
在 tflops_desc 的逐頁讀取中，沒有 TFLOPS 數值的報價跨頁始終留在最後。

不帶 limit 的請求和以往一樣回傳所有相符的型錄，上限 1,000 筆報價。超過時，它回傳前 1,000 筆、一個 next_cursor，以及回應標頭 X-Result-Truncated: true，讓不分頁的指令碼也知道它拿到的清單不完整。如果你可能讀到超過 1,000 筆報價，請用 limit 分頁。

回應欄位

欄位	型別	意義
`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_micro`	整數	整個切片每小時的價格
`storage_price_per_gb_hour_micro`	整數	硬碟每 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/summary" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

GET /v1/offers/summary 統計的是整個上架型錄，而不是篩選後的某一頁。市集頁面用它來產生篩選選項和頂端的概覽數字。

欄位	意義
`offers`	上架報價數，包括售完的
`available_offers`	目前至少有一份空閒的報價數
`machines`	至少上架一筆報價的不同機器數
`available_gpus`	閒置 GPU 數。每台機器只計它最大的空閒切片，絕不把各種切片規格相加：一台 8 卡機器的 1×、2×、4× 與 8× 型態用的是同一批卡
`min_price_per_hour_micro`、`max_price_per_hour_micro`	最便宜與最貴的切片價格；沒有任何上架報價時為 `null`
`models`	每個 GPU 型號一筆：`gpu_model`、`gpu_family`、`offers`、`available_offers`、`machines`、`available_gpus` 及其價格區間
`families`	每個 `gpu_family` 一筆，附 `offers` 與 `available_offers`。`Other` 排在最後。這些就是 `gpu_family` 接受的值
`regions`	每個 `country_code` 一筆，附 `offers` 與 `available_offers`。這些就是 `region` 接受的值
`generated_at`	統計的時間
`source`	`snapshot` 或 `live`，見下方

這些數字來自一份快照，每次型錄重新整理之後都會重建（source: snapshot），所以可能比一次部署晚最多一個重新整理週期。沒有近期快照時——最近五分鐘內沒有，或者重新整理間隔更長時最近三個週期內沒有，原因是重新整理被關閉或快照重建失敗——這個端點會為這一次請求即時統計型錄，並標為 source: live。清單端點一律是即時的。篩選選項和概覽數字用摘要；部署前請重新讀取報價上的 available_units。

取得單一報價

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 找它永遠不會成功。

列出報價​

篩選條件​

排序值​

分頁​

回應欄位​

型錄摘要​

取得單一報價​

型錄新鮮度​