跳到主要内容

模板

模板是实例部署时依据的启动配方：一个镜像、一种启动模式、端口、环境变量，以及一段可选的 onstart 脚本。概念说明见模板，各模式分别做什么见启动模式。

列出模板​

curl -s "$SUPERHEAT_API/v1/templates?tab=recommended&mode=jupyter" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

GET /v1/templates 返回 {"items": [...]}。

参数取值默认值返回
tabrecommended, mine, recent, popular, serverlessrecommendedrecommended：Superheat 精选的系统模板。mine：当前组织拥有的模板。recent：该组织部署过的模板，最近的在前。popular：按使用次数排序的系统模板和公开模板。serverless：占位项，不返回任何条目。
modessh, jupyter, args, vm无只返回该启动模式的模板
arch字符串无只返回 constraints.arch 匹配的模板
cuda字符串无只返回 constraints.cuda_min 完全相等的模板
q字符串，最多 200 个字符无对名称、描述或镜像做不区分大小写的子串匹配

tab 是一个封闭集合：不在其中的值会被以 422 拒绝，并附带一份点名该参数的校验错误列表。mode、arch 和 cuda 是自由格式的字符串匹配——一个没有任何东西用到的值只会返回空列表，而不是报错。

模板字段​

{
  "id": "b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56",
  "hash_id": "th_4c9e21b7f0a35d68c1e47b902d6af38150c9b7e4a2d81f6035c9e7b402a1d8f6",
  "name": "PyTorch (Jupyter)",
  "description": "PyTorch with a JupyterLab notebook server, ready to open.",
  "image": "vastai/pytorch",
  "tag": "[Automatic]",
  "docker_image": "vastai/pytorch",
  "repo": null,
  "href": null,
  "launch_mode": "jupyter",
  "args_str": null,
  "onstart": null,
  "env": [],
  "ports": [
    {"container_port": 8080, "protocol": "http", "label": "Jupyter", "public": true},
    {"container_port": 22, "protocol": "tcp", "label": "SSH", "public": true}
  ],
  "constraints": {"cuda_min": "12.1", "min_vram_mb": 8000, "recommended_disk_gb": 40},
  "jupyter_dir": "/workspace",
  "use_jupyter_lab": true,
  "registry_user": null,
  "has_registry_password": false,
  "readme": null,
  "visibility": "system",
  "owner_org_id": null,
  "created_by": null,
  "use_count": 1420,
  "coming_soon": false,
  "sort_order": 2,
  "is_active": true,
  "created_at": "2026-05-02T09:14:00.000Z",
  "updated_at": "2026-07-11T16:38:21.442Z",
  "tags": ["Jupyter", "SSH", "CUDA 12.1", "Automatic"]
}
字段类型含义
iduuid稳定的身份标识。部署时把它作为 template_id 传入。
hash_id字符串，th_ 前缀启动配方的内容哈希。配方一变就会重新生成。
image, tag, docker_image字符串镜像、它的标签，以及两者拼在一起的结果。tag 为 [Automatic] 时，会在启动时解析成与 CUDA 匹配的标签。
launch_modessh, jupyter, args, vm容器怎么启动
args_str字符串或 nullargs 模式用的参数
onstart字符串或 null以 SUPERHEAT_ONSTART 环境变量的形式送进容器的脚本，绝不会作为文件下发
env数组{key, value, secret}。除非模板归你的组织所有，否则标记为 secret 的值读回来是 null。
ports数组{container_port, protocol, label, public}，protocol 取 tcp、udp、http 或 https
constraints对象cuda_min、cuda_max、min_vram_mb、arch、vm_capable、recommended_disk_gb、selectors 中的任意几项
jupyter_dir, use_jupyter_lab字符串或 null、布尔JupyterLab 的工作目录，以及是否使用 Lab
registry_user, has_registry_password字符串或 null、布尔私有镜像仓库的用户名，以及是否存了密码。密码本身绝不会返回。
visibilitysystem, private, publicsystem 模板由 Superheat 精选，通过 API 不可修改
owner_org_id, created_byuuid 或 null所属组织和作者。系统模板上两者都是 null。
use_count, coming_soon, sort_order, is_active整数、布尔、整数、布尔目录元数据
tags字符串数组由启动模式和约束推导出来的分面标签

端口行为随启动模式而定：ssh 模板带容器端口 22，jupyter 模板带 22 和 8080，你声明的其他每个端口都会被标为应用端口。

JupyterLab 令牌由平台生成并下发给工作负载。它不由你设置，名为 JUPYTER_TOKEN 的环境变量覆盖项会被忽略——平台的覆盖层始终压过租用方提供的环境变量。

获取单个模板​

curl -s "$SUPERHEAT_API/v1/templates/b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

你能读取系统模板、任何组织的公开模板，以及你自己组织的私有模板。其他一律返回 404 TEMPLATE_NOT_FOUND——包括属于别的组织的私有模板，它会被报成不存在，而不是无权访问。

按哈希获取模板​

curl -s "$SUPERHEAT_API/v1/templates/by-hash/th_4c9e21b7f0a35d68c1e47b902d6af38150c9b7e4a2d81f6035c9e7b402a1d8f6" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

hash_id 是分享和启动用的标识。改名称、描述或 readme 这类表面修改不会让它变化；而只要启动配方一变，它就会重新生成——镜像、标签、模式、args、onstart、env、端口、约束、Jupyter 设置或镜像仓库用户名。

当你需要的就是自己测过的那份配方时，在流水线里锁定 hash_id。如果所有者改了配方，旧哈希就会以 404 TEMPLATE_NOT_FOUND 解析失败——这是一次响亮的失败，而不是悄悄换成另一个镜像。想跟着模板的后续修改走，就锁定 id。见分享与复制。

复制模板​

curl -s -X POST "$SUPERHEAT_API/v1/templates/b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56/duplicate" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

返回 201 和新模板。系统模板不能修改，所以复制就是你拿到一份可编辑副本的办法。

副本的属性值
所有者当前组织
可见性private
名称<source name> (copy)；如果这个名字已被占用，就是 (copy 2)、(copy 3)，依此类推
id 和 hash_id全新生成
标记为 secret 的环境变量值源模板归你的组织所有时保留；不是的话留空
私有镜像仓库凭据源模板归你的组织所有时保留；不是的话丢弃

其余一切——镜像、标签、启动模式、args、onstart、端口、约束、Jupyter 设置和 readme——都原样复制过来。部署副本之前，请在副本上重新填入你自己的密钥和镜像仓库凭据。