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. Superheat aún no ha publicado un nombre de host permanente para la API de inquilinos. Use la URL base de la tarjeta Endpoint de la API en la página Claves de API de la consola, que también trae un curl de ejemplo que puede copiar. 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.

Mantenga el host en esa única variable en lugar de escribirlo a mano en cada script: si la URL base cambia, solo tendrá que actualizar una línea.

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/summary`, `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 _micro son enteros que cuentan millonésimas de dólar estadounidense. Divida entre 1,000,000 para obtener dólares: 2290000 son $2.29 por hora, y un spend_micro 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_micro": 2290000,
      "storage_price_per_gb_hour_micro": 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.

URL base​

Qué cubre la API​

Qué no hace la API​

Campos de dinero​

Su primera solicitud​

Alcance de la organización​