Instancias

Una instancia es una oferta alquilada que ejecuta una plantilla. Estos endpoints hacen todo lo que hace la página Instancias.

Desplegar una instancia

curl -s -X POST "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11",
    "template_id": "b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56",
    "disk_gb": 60,
    "label": "sft-run-14",
    "ssh_key_id": "7a3c1e08-42bd-4f19-9d63-5b8e0c2a1f40",
    "env_overrides": [
      {"key": "HF_TOKEN", "value": "hf_...", "secret": true}
    ]
  }'

Campo	Tipo	Obligatorio	Notas
`offer_id`	uuid	Sí	Debe seguir estando `available`, o la llamada devuelve `409 OFFER_UNAVAILABLE`
`template_id`	uuid	Sí	Una plantilla de sistema, una pública, o una que pertenezca a su organización
`disk_gb`	entero	Sí	Entre 10 y 20000, y no mayor que el `machine.disk_gb` del host
`label`	cadena, hasta 64 caracteres	No	Se muestra en la lista de la consola. Su valor predeterminado es `null`.
`ssh_key_id`	uuid	No	Debe ser una clave de la cuenta de quien tenga la credencial. Sin ella, la instancia no tiene ninguna clave autorizada y no podrá conectarse por SSH.
`env_overrides`	array de `{key, value, secret}`	No	Se fusiona sobre el `env` de la plantilla, emparejado por clave. Una entrada con valor `null` se descarta.

Las sustituciones de entorno se fusionan sobre el env de la plantilla, pero la capa propia de la plataforma gana sobre ambas. No puede ensombrecer JUPYTER_TOKEN ni GPU_COUNT.

La respuesta es 201 con la instancia. La facturación empieza cuando la carga de trabajo llega realmente a running, no en el momento de esta llamada.

Un despliegue gasta dinero en el momento en que se ejecuta

El saldo se comprueba al desplegar, no se reserva. El tiempo de GPU se factura por segundo mientras la instancia está en ejecución, y el disco por GB y por hora mientras está detenida. Con saldo cero, las instancias en ejecución se detienen automáticamente, y en −$5 se destruyen. Consulte Cómo funciona la facturación.

Campos de la instancia

{
  "id": "e08b5f27-1c4a-4d90-b3e6-72a9d1f45c83",
  "label": "sft-run-14",
  "status": "creating",
  "disk_gb": 60,
  "price_per_hour_microusd": 2290000,
  "storage_price_per_gb_hour_microusd": 250,
  "ssh_host": "sh-us-tx-01.ssh.superheat.dev",
  "ssh_port": 41207,
  "ssh_user": "root",
  "jupyter_url": null,
  "open_url": null,
  "created_at": "2026-07-24T11:12:03.771Z",
  "started_at": null,
  "status_changed_at": "2026-07-24T11:12:03.771Z",
  "destroyed_at": null,
  "spend_microusd": 0,
  "deployed_by": "you@example.com",
  "offer": { "id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11" },
  "template": { "id": "b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56" }
}

offer y template son los objetos completos documentados en Ofertas y Plantillas; aquí se muestran abreviados.

Campo	Tipo	Significado
`status`	cadena	Uno de `creating`, `starting`, `running`, `stopping`, `stopped`, `destroying`, `destroyed`, `error`. Consulte Estados de instancia.
`disk_gb`	entero	El disco que pidió, facturado por GB y por hora mientras está detenida
`price_per_hour_microusd`	entero	Tarifa congelada desde la oferta al momento de alquilar, para el bloque completo
`storage_price_per_gb_hour_microusd`	entero	Tarifa de disco congelada al momento de alquilar
`ssh_host`, `ssh_port`, `ssh_user`	cadena, entero, cadena	El destino de conexión. El puerto se asigna desde el rango publicado del host y nunca es el 22.
`jupyter_url`	cadena o null	Punto de entrada de JupyterLab, una vez que una plantilla `jupyter` informa uno
`open_url`	cadena o null	El endpoint del botón de abrir de la plantilla, una vez que se informa
`created_at`, `started_at`, `status_changed_at`, `destroyed_at`	marcas de tiempo	`started_at` se establece la primera vez que se ejecuta la carga de trabajo
`spend_microusd`	entero	Cargos liquidados de esta instancia hasta ahora
`deployed_by`	cadena	Correo del miembro que la desplegó

Listar instancias

curl -s "$SUPERHEAT_API/v1/instances" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

Devuelve {"items": [...]} para la organización activa, de la más nueva a la más antigua. Las instancias destruidas quedan excluidas a menos que pase include_destroyed=true.

Obtener una sola instancia

curl -s "$SUPERHEAT_API/v1/instances/e08b5f27-1c4a-4d90-b3e6-72a9d1f45c83" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

Los ids desconocidos, y las instancias que pertenecen a otra organización, devuelven 404 INSTANCE_NOT_FOUND.

Detener, iniciar y destruir

Solicitud	Efecto	Permitido desde
`POST /v1/instances/{id}/stop`	Apaga el contenedor, conserva el disco y mantiene reservada la ranura de GPU. El estado pasa a `stopping` y luego a `stopped`.	`running`
`POST /v1/instances/{id}/start`	Vuelve a levantar una instancia detenida sobre el mismo disco. El estado pasa a `starting` y luego a `running`.	`stopped`
`DELETE /v1/instances/{id}`	Desmonta la instancia y libera el bloque. El estado pasa a `destroying` y luego a `destroyed`.	`running`, `stopped`, `error`

curl -s -X POST "$SUPERHEAT_API/v1/instances/$INSTANCE_ID/stop" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

Las tres devuelven el objeto completo de la instancia en su nuevo estado de transición: la transición termina de forma asíncrona, así que sondee hasta que el estado se estabilice.

Llamar a una de estas desde un estado que no lo permite devuelve 409 INVALID_STATE con un mensaje que nombra el estado actual, por ejemplo Cannot start an instance while it is running. Iniciar también vuelve a comprobar el saldo y puede devolver 402 INSUFFICIENT_BALANCE.

Destruir elimina el disco

DELETE es definitivo: el contenedor, el disco y todo lo que hay en él desaparecen, y la oferta vuelve al mercado. Detenga en su lugar si quiere que sus datos lo estén esperando. Consulte Detener vs. destruir.

Logs

curl -s "$SUPERHEAT_API/v1/instances/$INSTANCE_ID/logs?tail=50" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

{
  "lines": [
    "[2026-07-24 11:12:07] superheat-agent: pulling image vastai/pytorch",
    "[2026-07-24 11:12:11] superheat-agent: image ready, creating container",
    "[2026-07-24 11:12:13] nvidia-smi: detected 1 GPU(s), driver 570.86",
    "[2026-07-24 11:12:14] sshd: listening on 0.0.0.0:41207",
    "[2026-07-24 11:12:15] superheat-agent: instance is ready"
  ]
}

Parámetro	Rango	Predeterminado
`tail`	1 a 1000	200

Los valores fuera de ese rango se rechazan con 422. lines está vacío hasta que la carga de trabajo se haya ejecutado por primera vez, así que una instancia en creating no devuelve nada. No hay endpoint de streaming; sondee este — la consola lo actualiza cada tres segundos. Consulte Leer los logs.

Desplegar y conectarse, de principio a fin

Este es el camino completo desde una shell vacía hasta una sesión SSH. Da por hecho que tiene jq, una clave SSH ya agregada en la consola y créditos en el saldo.

1. Defina sus credenciales. Las claves SSH pertenecen a su cuenta y no a la organización, así que listarlas necesita un token de sesión; todo lo demás funciona con la clave de API.

export SUPERHEAT_API="https://<your-superheat-api-host>"
export SUPERHEAT_KEY="shk_your_key_here"
AUTH=(-H "Authorization: Bearer $SUPERHEAT_KEY")

2. Encuentre el id de la clave SSH con un token de sesión de un navegador con la sesión iniciada:

curl -s "$SUPERHEAT_API/v1/ssh-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  | jq -r '.items[] | "\(.id)  \(.name)  \(.fingerprint)"'

7a3c1e08-42bd-4f19-9d63-5b8e0c2a1f40  laptop  SHA256:Yx1r0oW2fS7Tq8kJ3mN4pB6vC9dE0gH2iK5lM8nP1qR

SSH_KEY_ID="7a3c1e08-42bd-4f19-9d63-5b8e0c2a1f40"

3. Elija el bloque de una sola H100 más barato:

OFFER_ID=$(curl -s "$SUPERHEAT_API/v1/offers?gpu_model=H100%20SXM&num_gpus=1&sort=price_asc" \
  "${AUTH[@]}" | jq -r '.items[0].id')

4. Elija una plantilla SSH:

TEMPLATE_ID=$(curl -s "$SUPERHEAT_API/v1/templates?tab=recommended&mode=ssh" \
  "${AUTH[@]}" | jq -r '.items[0].id')

5. Despliegue:

INSTANCE_ID=$(curl -s -X POST "$SUPERHEAT_API/v1/instances" \
  "${AUTH[@]}" -H "Content-Type: application/json" \
  -d "{\"offer_id\":\"$OFFER_ID\",\"template_id\":\"$TEMPLATE_ID\",\"disk_gb\":60,\"label\":\"api-demo\",\"ssh_key_id\":\"$SSH_KEY_ID\"}" \
  | jq -r '.id')

6. Espere a running:

while :; do
  STATUS=$(curl -s "$SUPERHEAT_API/v1/instances/$INSTANCE_ID" "${AUTH[@]}" | jq -r '.status')
  echo "$STATUS"
  case "$STATUS" in
    running) break ;;
    error|destroyed) exit 1 ;;
  esac
  sleep 3
done

7. Construya el comando de conexión a partir de la propia instancia en lugar de reconstruirlo: el puerto se asigna por instancia:

curl -s "$SUPERHEAT_API/v1/instances/$INSTANCE_ID" "${AUTH[@]}" \
  | jq -r '"ssh -p \(.ssh_port) \(.ssh_user)@\(.ssh_host)"'

ssh -p 41207 root@sh-us-tx-01.ssh.superheat.dev

8. Conéctese y compruebe las GPUs:

ssh -p 41207 root@sh-us-tx-01.ssh.superheat.dev nvidia-smi

9. Detenga cuando haga una pausa, destruya cuando haya terminado:

curl -s -X POST "$SUPERHEAT_API/v1/instances/$INSTANCE_ID/stop" "${AUTH[@]}" | jq -r '.status'
curl -s -X DELETE "$SUPERHEAT_API/v1/instances/$INSTANCE_ID" "${AUTH[@]}" | jq -r '.status'

Desplegar una instancia​

Campos de la instancia​

Listar instancias​

Obtener una sola instancia​

Detener, iniciar y destruir​

Logs​

Desplegar y conectarse, de principio a fin​