跳至主要內容

範本

範本是執行個體部署時所依據的啟動配方：一個映像檔、一種啟動模式、連接埠、環境變數，以及選用的 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}。除非該範本由你的組織擁有，否則祕密值讀回來會是 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 這類外觀上的修改不會改變它，而只要啟動配方一變動就會重新產生 —— 映像檔、標籤、模式、引數、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全新產生
祕密的 env 值來源由你的組織擁有時會保留；否則留空
私有登錄檔憑證來源由你的組織擁有時會保留；否則捨棄

其他所有東西 —— 映像檔、標籤、啟動模式、引數、onstart、連接埠、限制條件、Jupyter 設定與 readme —— 都會原樣複製。部署副本之前，請在上面重新輸入你自己的祕密資訊與登錄檔憑證。