Descripción general de la API

Todo lo que hace la consola lo hace llamando a esta API. Puede explorar ofertas, desplegar una instancia, ver sus logs, detenerla y destruirla desde un script, con la misma organización y el mismo saldo por detrás.

URL base

Todos los endpoints viven bajo el prefijo /v1 en el host de la API de Superheat. Las solicitudes y las respuestas son JSON. Defina dos variables para que los ejemplos de esta sección funcionen tal como están escritos:

export SUPERHEAT_API="https://<your-superheat-api-host>"
export SUPERHEAT_KEY="shk_your_key_here"

Todas las rutas de abajo están escritas de forma relativa a ese host: /v1/offers significa $SUPERHEAT_API/v1/offers.

Qué cubre la API

Área	Endpoints	Documentado en
Estado del servicio	GET /v1/health	Esta página
Catálogo	GET /v1/offers, GET /v1/offers/{id}, GET /v1/catalog/status	Ofertas
Plantillas	GET /v1/templates, GET /v1/templates/{id}, GET /v1/templates/by-hash/{hash_id}, POST /v1/templates/{id}/duplicate	Plantillas
Instancias	POST /v1/instances, GET /v1/instances, GET /v1/instances/{id}, POST /v1/instances/{id}/stop, POST /v1/instances/{id}/start, DELETE /v1/instances/{id}, GET /v1/instances/{id}/logs	Instancias
Claves	GET /v1/api-keys, POST /v1/api-keys, DELETE /v1/api-keys/{id}	Claves de API

Qué no hace la API

No disponible	Haga esto en su lugar
Agregar créditos con una clave de API	El proceso de pago es exclusivo de administradores y rechaza las claves de API. Recargue en la consola, en Facturación.
Endpoints de cuenta con una clave de API	/v1/me y /v1/ssh-keys requieren una sesión iniciada. Agregue claves SSH en la consola antes de automatizar despliegues.
Logs en streaming	Sondee GET /v1/instances/{id}/logs?tail=N. La consola lo sondea cada tres segundos.
Elegir una máquina, un host o una ubicación	Usted alquila una oferta. Superheat decide dónde se ejecuta.
Fijar su propio precio	Los precios los fija Superheat y quedan congelados en la instancia cuando usted alquila.

Campos de dinero

Los campos cuyo nombre termina en _microusd son enteros que cuentan millonésimas de dólar. Divida entre 1,000,000 para obtener dólares: 2290000 son $2.29 por hora, y un spend_microusd de 410000 son $0.41 gastados hasta ahora.

Su primera solicitud

GET /v1/health no necesita credenciales, así que es la forma más rápida de confirmar que puede llegar a la API:

curl -s -i "$SUPERHEAT_API/v1/health"

{
  "status": "ok",
  "version": "0.1.0",
  "commit": "9f2c1ab",
  "app_env": "production",
  "provisioner": "dispatch",
  "inventory_sync_enabled": true,
  "database": true
}

Campo	Tipo	Significado
status	cadena	ok, o degraded cuando una comprobación falló
version	cadena	Versión de la API
commit	cadena o null	Commit de git con el que se compiló la API desplegada, null fuera de una compilación desplegada
app_env	cadena	Qué entorno respondió, por ejemplo production
provisioner	cadena	dispatch para hardware real, simulated para una flota falsa
inventory_sync_enabled	booleano	Si el catálogo se está actualizando desde inventario en vivo
database	booleano	Si una consulta real acaba de ir y volver de la base de datos

El manejador ejecuta un SELECT 1 contra la base de datos con un techo de 3 segundos, en lugar de devolver un literal fijo. Si eso falla, responde 503 con la misma forma de cuerpo, status en degraded y database en false, así que compruebe el estado HTTP y no solo la presencia de un cuerpo. Los tres campos de entorno están ahí para que una API que sirve calladamente una flota simulada sea visible desde fuera; un provisioner de simulated significa que las instancias que despliegue no son máquinas reales.

Todo lo demás necesita un bearer token. Cree primero una clave de API (Claves de API) y luego liste las tres ofertas más baratas:

curl -s "$SUPERHEAT_API/v1/offers?sort=price_asc" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

{
  "items": [
    {
      "id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11",
      "gpu_model": "H100 SXM",
      "num_gpus": 1,
      "vram_gb": 80,
      "tflops": 198.0,
      "cuda_version": "12.8",
      "vm_capable": false,
      "disk_quota_capable": false,
      "price_per_hour_microusd": 2290000,
      "storage_price_per_gb_hour_microusd": 250,
      "max_duration_hours": null,
      "status": "available",
      "available_units": 3,
      "capacity_units": 8,
      "machine": {
        "hostname": "sh-us-tx-01",
        "region": "US-TX",
        "country_code": "US",
        "cpu_model": "Intel Xeon Platinum 8480+",
        "cpu_cores": 112,
        "ram_gb": 2048,
        "disk_type": "nvme",
        "disk_gb": 15000,
        "net_up_mbps": 8000,
        "net_down_mbps": 8000,
        "pcie_gen": 5,
        "pcie_width": 16,
        "reliability": 0.998,
        "verified": true,
        "next_maintenance": null
      }
    }
  ]
}

A partir de ahí, Instancias recorre el camino completo de desplegar y conectarse.

Alcance de la organización

Cada objeto pertenece a una organización, nunca a un usuario directamente. Una solicitud sin encabezado X-Org-Id se ejecuta contra su organización personal; una clave de API siempre se ejecuta contra la organización en la que fue creada. Consulte Autenticación.