HELPER VPS

Inicio rápido de la API de VPS: crea tu clave API y tu primer servidor

La API de HELPER VPS es una API REST que intercambia JSON por HTTPS. Con una sola clave consultas planes, creas servidores, gestionas el encendido, renuevas y borras. Síguela desde la primera petición hasta crear y borrar un servidor.

Paso 1. Crear la clave API

Puedes crear una clave API después de tu primer pago. Consulta la guía de pago con USDT para saber cómo pagar.

  • Pulsa crear clave API en el menú de claves API de tu cuenta.
  • La clave que empieza por hvp_ se muestra una sola vez. Cópiala al instante y guárdala en un gestor de contraseñas.
  • En pantalla solo queda el final de la clave, para que reconozcas qué clave usas.
  • Al pulsar crear nueva clave aparece una clave nueva y la anterior deja de funcionar al instante.

La clave da acceso a toda la cuenta, así que úsala en variables de entorno para que no aparezca en repositorios de código ni al compartir pantalla. Los ejemplos de esta guía empiezan guardando la clave en una variable en la terminal.

Terminal
export HVP_KEY=hvp_YOUR_KEY_HERE
export HVP=https://helpervps.com/api/v1

Paso 2. Autenticación y primera petición

Todas las peticiones se envían bajo la dirección base https://helpervps.com/api/v1 con la cabecera Authorization: Bearer clave. Como primera petición, carga tu lista de servidores. Si no tienes servidores, vuelve una lista vacía [].

Terminal
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Cada cuenta puede enviar hasta 300 peticiones por minuto, y crear servidores hasta 10 veces cada 10 minutos. Para peticiones repetidas que comprueban el estado, unos segundos de intervalo van sobrados. Todas las respuestas son JSON, y si hay un error vuelven con su código de estado en la forma {"error": "code"}.

Paso 3. Elegir plan, región e imagen

Todos los valores para crear un servidor salen del catálogo. GET /catalog devuelve de una vez los planes en venta (plans), las regiones (locations), las imágenes (images) y las opciones adicionales (addons). Con jq es cómodo ver solo la parte que necesitas.

Terminal
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'
  • Código de plan: indica tipo y tamaño, como s1 o s2. type es basic (SSD estándar), fast (NVMe de alto rendimiento), cpu (CPU dedicada) o mem (alta memoria). monthly es la tarifa mensual en dólares estadounidenses.
  • Código de región: el nombre de la ciudad, como frankfurt, singapore o seoul.
  • Código de imagen: sistemas operativos como ubuntu-24-04, debian-13 o almalinux-10 y apps como app-docker o app-wordpress.
  • Opciones adicionales: porcentaje de copias automáticas, tamaños y tarifa por GB del disco adicional y tarifa de protección DDoS. Las opciones que no están a la venta vienen como null.

Si no lo tienes, instálalo con apt install -y jq en Ubuntu y con brew install jq en Mac. Es la misma lista que eliges en pantalla, así que es cómodo ver las diferencias entre planes también en la página de precios.

Paso 4. Crear el servidor

Envía el plan, la ubicación, la imagen y el nombre como JSON a POST /servers. Paga por el primer período del plan elegido y comenzará la creación del servidor.

Terminal
curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

Si tiene éxito, vuelve el código de estado 201 con la información del servidor. id es el código del servidor con la forma S-XXXX-XXXX-XXXX, y lo usarás en todas las peticiones siguientes. root_password viene una sola vez en esta respuesta, así que guárdalo al instante. También puedes verlo en la página del servidor durante 7 días.

  • label: el nombre del servidor. Hasta 40 caracteres con letras inglesas, números, puntos y guiones; los demás caracteres se convierten en guiones.
  • backups: con true se activan las copias automáticas.
  • extra_disk_gb: tamaño del disco de bloque NVMe adicional. Pon uno de los valores sizes_gb del catálogo (50, 100, 250, 500, 1000).
  • ddos_protection: con true se activa la protección DDoS.

Las tarifas de las opciones se suman a la tarifa mensual del servidor, aparecen en monthly de la respuesta y se renuevan automáticamente en cada fecha de pago por el mismo importe. Cada cuenta puede crear hasta 10 servidores.

Paso 5. Comprobar el estado y conectarte

Un servidor nuevo empieza en estado creating y, al estar listo, pasa a running y se rellena la dirección ipv4. El bucle de abajo mira el estado cada 10 segundos y muestra la IP cuando pasa a running. Cambia el código del servidor por el de tu servidor.

Terminal
ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

El estado es uno de los siguientes: creating, running, stopped, rebooting, installing, suspended o check. suspended significa que el servidor se pausó porque no se renovó en la fecha de facturación, y check significa que estamos verificando el resultado de la configuración del servidor. Una vez que aparezca la IP, conéctate con ssh root@IP. Cómo conectarte está en la guía del primer inicio de sesión.

Paso 6. Encendido, renovación y borrado

Terminal
curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"
  • start: enciende un servidor detenido (stopped).
  • stop, reboot: apaga o reinicia un servidor en ejecución (running).
  • renew: paga por 1, 3, 6 o 12 meses más ahora. Un servidor suspendido también vuelve con esta solicitud.
  • DELETE: borra el servidor y el disco y devuelve {"state": "deleted"}. El tiempo restante del mes ya pagado no se reembolsa.

Si envías una tarea que no se puede hacer en el estado actual, vuelve 409 wrong_state. Por ejemplo, al enviar start a un servidor ya encendido. La reinstalación y la creación de una nueva contraseña de root se hacen en la página del servidor. Los pasos están en la guía de reinstalación.

El mismo proceso en Python

El mismo flujo escrito como script de Python queda así. Usa la biblioteca requests (pip install requests).

create_server.py
import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Códigos de error frecuentes

  • 401 unauthorized: falta la clave o es incorrecta. Comprueba que la cabecera tiene la forma Authorization: Bearer hvp_....
  • 403 not_allowed: se abre una vez que se confirma tu primer pago.
  • 400 bad_request: el nombre o el valor de un campo es incorrecto. Usa los códigos tal cual aparecen en el catálogo.
  • 402 not_enough_balance: el importe del pago es inferior a $25. Envía nuevamente con al menos $25.
  • 409 limit: has alcanzado el número de servidores que puede crear tu cuenta.
  • 409 not_created: no se pudo crear el servidor, y la tarifa se devuelve al crédito de tu cuenta.
  • 202 checking: estamos verificando el resultado de la configuración del servidor. No envíes la misma solicitud nuevamente; revisa tu lista de servidores. El servidor se completará o la tarifa se devolverá al crédito de tu cuenta.
  • 404 not_found: código de servidor o dirección que no está en tu cuenta.
  • 409 wrong_state: tarea que no se puede hacer en el estado actual.
  • 429 rate_limited: has alcanzado el límite de peticiones por minuto. Espera un momento y vuelve a enviar.

Todos los endpoints, campos de respuesta y ejemplos están en la documentación de la API. Lo que puedes hacer con la API y sus usos se ven en la página API de VPS.

Guías relacionadas

Configuraciones que conviene hacer a continuación de esta guía.

Ver todas las guías