报价
一份报价就是一台机器上可租用的一个切片：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。系列由服务器根据规范化后的型号名得出：本单元机群里的 H800 和 H20 归入 Hopper，A800 归入 Ampere，L20 归入 Ada。目录里当前有哪些系列、各有多少报价，见目录摘要。一个没有任何在架报价的系列返回空页，而不是错误 |
q | 字符串，最多 100 个字符 | 无 | 自由文本搜索：在 GPU 型号、主机名和区域连在一起的文本中做不区分大小写的子串匹配。% 和 _ 按字面匹配，不是通配符 |
num_gpus | 整数 | 无 | 切片大小：1、2、4 或 8 |
region | 字符串 | 无 | 报价上显示的完整区域代码，或国家/地区代码，例如 CN。精确匹配，区分大小写 |
min_vram_gb | 整数 | 无 | 每张 GPU 显存至少这么多的报价 |
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 的显存，最高的在前 |
排序值相同的报价按 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拒绝；请原样传回next_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 的显存 |
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 卡机器会把它的 1x 形态卖两次，所以同一个形态可以既被租走、又同时仍然可租。
disk_quota_capable 说的是这台机器能不能把你按住在你申请的那个 disk_gb 上。无论哪种情况，你都是按那个数字计费的。只有当主机把 Docker 的存储放到了带项目配额的 XFS 上，它才是 true，而那是机器所有者的一个可选步骤，所以 false 会很常见。在一台 false 的机器上，租这台机器的所有人共用一个卷，一个写得比他买的多的同租者可以在你脚下把它写满；disk_gb 是目录卖给你的一个上限，不是给你留出来的一份额度。在一台 true 的机器上，它是按实例强制执行的配额。控制台在报价卡片上把这一点显示为有保障还是共享。
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。
region 是运营方为主机填写的位置，country_code 取自它的前两个字母；运营方没有填写位置时，两者分别是 UNKNOWN 和 XX。参见区域。
machine.disk_gb 是整个卷的大小，它是你部署时能申请的 disk_gb 的一个上界，而不是保证你能拿到那么多：有 50 GB 是留给主机自己的，而这台机器上其他租客已经占掉的部分也要从剩下的里面扣。申请超过剩余量会返回 409 MACHINE_DISK_EXHAUSTED，并附上当时真正可用的数字。
machine.reliability 在这台主机从未被测量过时是 null，这和 0.0 不是同一个说法。测过的值是 0 到 1 之间的小数，保留四位小数——控制台把它显示成带两位小数的百分比。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 轮询它永远不会成功。