Plantillas
Una plantilla es la receta de lanzamiento desde la que se despliega una instancia: una imagen, un modo de lanzamiento, puertos, variables de entorno y un script de inicio opcional. Consulte Plantillas para el concepto y Modos de lanzamiento para saber qué hace cada modo.
Listar plantillas
curl -s "$SUPERHEAT_API/v1/templates?tab=recommended&mode=jupyter" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
GET /v1/templates devuelve {"items": [...]}.
| Parámetro | Valores | Predeterminado | Devuelve |
|---|---|---|---|
tab | recommended, mine, recent, popular, serverless | recommended | recommended: las plantillas de sistema curadas por Superheat. mine: plantillas propiedad de la organización activa. recent: plantillas que la organización ha desplegado, de la más reciente a la más antigua. popular: plantillas de sistema y públicas por número de usos. serverless: un marcador de posición que no devuelve elementos. |
mode | ssh, jupyter, args, vm | ninguno | Solo plantillas con ese modo de lanzamiento |
arch | cadena | ninguno | Solo plantillas cuyo constraints.arch coincida |
cuda | cadena | ninguno | Solo plantillas cuyo constraints.cuda_min coincida exactamente |
q | cadena, hasta 200 caracteres | ninguno | Coincidencia de subcadena, sin distinguir mayúsculas, en el nombre, la descripción o la imagen |
tab es un conjunto cerrado: un valor fuera de él se rechaza con 422 y una lista de validación que nombra el parámetro. mode, arch y cuda son coincidencias de cadena de forma libre: un valor que nadie usa devuelve una lista vacía en lugar de un error.
Campos de una plantilla
{
"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"]
}
| Campo | Tipo | Significado |
|---|---|---|
id | uuid | Identidad estable. Páselo como template_id al desplegar. |
hash_id | cadena, prefijo th_ | Hash del contenido de la receta de lanzamiento. Se vuelve a acuñar cada vez que la receta cambia. |
image, tag, docker_image | cadena | La imagen, su etiqueta y ambas unidas. Un tag de [Automatic] se resuelve al lanzar en una etiqueta que coincida con la versión de CUDA. |
launch_mode | ssh, jupyter, args, vm | Cómo se inicia el contenedor |
args_str | cadena o null | Argumentos para el modo args |
onstart | cadena o null | Script entregado al contenedor como la variable de entorno SUPERHEAT_ONSTART, nunca como un archivo |
env | array | {key, value, secret}. Los valores secretos se leen como null a menos que la plantilla sea de su organización. |
ports | array | {container_port, protocol, label, public} con el protocolo tcp, udp, http o https |
constraints | objeto | Cualquiera de cuda_min, cuda_max, min_vram_mb, arch, vm_capable, recommended_disk_gb, selectors |
jupyter_dir, use_jupyter_lab | cadena o null, booleano | Directorio de trabajo de JupyterLab y si se usa Lab |
registry_user, has_registry_password | cadena o null, booleano | Nombre de usuario del registro privado, y si hay una contraseña almacenada. La contraseña en sí nunca se devuelve. |
visibility | system, private, public | Las plantillas system las cura Superheat y son inmutables a través de la API |
owner_org_id, created_by | uuid o null | Organización propietaria y autor. Ambos son null en las plantillas de sistema. |
use_count, coming_soon, sort_order, is_active | entero, booleano, entero, booleano | Metadatos del catálogo |
tags | array de cadenas | Etiquetas de faceta derivadas del modo de lanzamiento y de las restricciones |
El comportamiento de los puertos sigue al modo de lanzamiento: las plantillas ssh llevan el puerto de contenedor 22, las plantillas jupyter llevan el 22 y el 8080, y cualquier otro puerto que usted declare se etiqueta como puerto de aplicación.
El token de JupyterLab lo acuña la plataforma y se pasa a la carga de trabajo. Usted no lo define, y una sustitución de entorno llamada JUPYTER_TOKEN se ignora: la capa de la plataforma siempre gana sobre las variables de entorno que aporta quien alquila.
Obtener una sola plantilla
curl -s "$SUPERHEAT_API/v1/templates/b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
Puede leer las plantillas de sistema, las plantillas públicas de cualquier organización y las plantillas privadas de su propia organización. Cualquier otra cosa devuelve 404 TEMPLATE_NOT_FOUND, incluida una plantilla privada que pertenezca a otra organización, que se reporta como inexistente y no como prohibida.
Obtener una plantilla por hash
curl -s "$SUPERHEAT_API/v1/templates/by-hash/th_4c9e21b7f0a35d68c1e47b902d6af38150c9b7e4a2d81f6035c9e7b402a1d8f6" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
hash_id es el token para compartir y lanzar. Es estable ante ediciones cosméticas como el nombre, la descripción o el readme, y se vuelve a acuñar cada vez que cambia la receta de lanzamiento: la imagen, la etiqueta, el modo, los argumentos, el script de inicio, el entorno, los puertos, las restricciones, la configuración de Jupyter o el usuario del registro.
Fije hash_id en un pipeline cuando necesite exactamente la receta que probó. Si el propietario cambia la receta, el hash antiguo deja de resolverse con 404 TEMPLATE_NOT_FOUND, que es un fallo ruidoso en lugar de un cambio silencioso a otra imagen. Fije id cuando quiera seguir las ediciones de la plantilla. Consulte Compartir y duplicar.
Duplicar una plantilla
curl -s -X POST "$SUPERHEAT_API/v1/templates/b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56/duplicate" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
Devuelve 201 con la nueva plantilla. Duplicar es la forma de obtener una copia editable de una plantilla de sistema, dado que las plantillas de sistema no se pueden modificar.
| Propiedad de la copia | Valor |
|---|---|
| Propietario | La organización activa |
| Visibilidad | private |
| Nombre | <source name> (copy), con (copy 2), (copy 3) y así sucesivamente si ese nombre ya está tomado |
id y hash_id | Recién acuñados |
| Valores de entorno secretos | Se conservan si su organización era dueña del origen; quedan en blanco si no lo era |
| Credenciales de registro privado | Se conservan si su organización era dueña del origen; se descartan si no lo era |
Todo lo demás —imagen, etiqueta, modo de lanzamiento, argumentos, script de inicio, puertos, restricciones, configuración de Jupyter y readme— se copia tal cual. Vuelva a introducir sus propios secretos y credenciales de registro en la copia antes de desplegarla.