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 una página: {"items": [...], "next_cursor": "…"}. Las filas de la lista llevan readme y onstart como null; pida una sola plantilla para obtenerlos.
| 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 |
limit | de 1 a 200 | 100 | Plantillas por página |
cursor | cadena | ninguno | El next_cursor de la página anterior |
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 de hasta 32 caracteres: un valor que nadie usa devuelve una lista vacía en lugar de un error.
next_cursor es null en la última página. Si no, devuélvalo sin cambios, con los mismos filtros, para obtener la siguiente; trátelo como opaco. Un cliente que no pagina obtiene las primeras 100, que abarcan todas las plantillas curadas:
CURSOR=""
while :; do
PAGE=$(curl -s "$SUPERHEAT_API/v1/templates?tab=popular&limit=200${CURSOR:+&cursor=$CURSOR}" \
-H "Authorization: Bearer $SUPERHEAT_KEY")
echo "$PAGE" | jq -r '.items[].name'
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty')
[ -z "$CURSOR" ] && break
done
Un cursor que la API no emitió se rechaza con 422 INVALID_CURSOR.
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. null en las filas de la lista y en la plantilla incrustada en una instancia |
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, auth} con el protocolo tcp, udp, http o https. auth es proxy, app o null: si el puerto exige el token de acceso de la instancia; consulte Exigir el token de acceso |
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. Ese mismo token es el token de acceso de la instancia, que un puerto puede exigir mediante su campo auth; consulte Exigir el token de acceso.
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.