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`	布尔	刚刚是否真的有一次查询往返到了数据库

这个处理函数会以 3 秒为上限对数据库执行一次 SELECT 1，而不是返回一个写死的字面量。如果那次查询失败，它返回 503，body 结构相同，status 为 degraded、database 为 false —— 所以要看 HTTP 状态码，而不只是看有没有 body。那三个环境字段的存在，是为了让"一个 API 悄悄在服务一个模拟机群"这件事从外面就能看出来；provisioner 为 simulated 意味着你部署出来的实例不是真机器。

其他所有请求都需要 bearer 令牌。先创建一个 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 不做的事​

金额字段​

你的第一个请求​

组织范围​