HELPER VPS

Швидкий старт VPS API: створення ключа API й першого сервера

API HELPER VPS це REST API, що обмінюється JSON через HTTPS. Одним ключем можна отримувати конфігурації, створювати сервери, керувати живленням, продовжувати й видаляти їх. Пройдіть шлях від першого запиту до створення й видалення одного сервера.

Крок 1. Створіть ключ API

Ви можете створити API ключ після першої оплати. Дивіться посібник з оплати USDT для отримання інструкцій щодо оплати.

  • Натисніть «Створити ключ API» в меню ключів API в акаунті.
  • Ключ, що починається з hvp_, показується лише один раз. Одразу скопіюйте його й збережіть у менеджері паролів.
  • На екрані лишаються тільки останні символи ключа, щоб було видно, який ключ використовується.
  • Після натискання «Створити новий ключ» з'являється новий ключ, а старий одразу перестає працювати.

Ключ дає доступ до всього акаунта, тож використовуйте його через змінну середовища, щоб він не потрапив до репозиторію коду чи на демонстрацію екрана. Приклади в цьому посібнику починаються з того, що ключ зберігається в змінній у терміналі.

Термінал
export HVP_KEY=hvp_YOUR_KEY_HERE
export HVP=https://helpervps.com/api/v1

Крок 2. Автентифікація й перший запит

Усі запити надсилаються на базову адресу https://helpervps.com/api/v1 із заголовком Authorization: Bearer ключ. Першим запитом отримайте список своїх серверів. Якщо серверів немає, повернеться порожній список [].

Термінал
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

З одного акаунта можна надсилати до 300 запитів на хвилину, а створювати сервери до 10 разів за 10 хвилин. Для повторюваних запитів перевірки статусу досить інтервалу в кілька секунд. Усі відповіді приходять у JSON, а в разі помилки повертаються з кодом статусу у вигляді {"error": "code"}.

Крок 3. Оберіть конфігурацію, регіон і образ

Усі значення для створення сервера беруться з каталогу. GET /catalog за один раз повертає доступні конфігурації (plans), регіони (locations), образи (images) і додаткові опції (addons). З jq зручно обирати лише потрібні частини.

Термінал
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'
  • Код конфігурації: наприклад, s1 чи s2, позначає тип і розмір. type буває basic (стандартний SSD), fast (високопродуктивний NVMe), cpu (виділений CPU) і mem (великий обсяг пам'яті). monthly це місячна ціна в доларах США.
  • Код регіону: назва міста, наприклад frankfurt, singapore чи seoul.
  • Код образу: операційні системи, наприклад ubuntu-24-04, debian-13 чи almalinux-10, і застосунки, наприклад app-docker чи app-wordpress.
  • Додаткові опції: частка вартості автоматичних копій, розміри додаткового диска й ціна за GB, ціна захисту від DDoS. Недоступні опції приходять як null.

Якщо jq немає, в Ubuntu встановіть його командою apt install -y jq, у macOS brew install jq. Це той самий список, що й в інтерфейсі, тож різницю між конфігураціями зручно дивитися разом зі сторінкою цін.

Крок 4. Створіть сервер

Надішліть план, локацію, образ та ім'я у форматі JSON до POST /servers. Оплатіть перший термін обраного плану, і почнеться створення сервера.

Термінал
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"}'

У разі успіху повернеться код статусу 201 і дані сервера. id це код сервера вигляду S-XXXX-XXXX-XXXX, який використовується в усіх подальших запитах. root_password приходить у цій відповіді лише один раз, тож одразу збережіть його. На сторінці сервера він теж видний 7 днів.

  • label: ім'я сервера. До 40 символів з латинських літер, цифр, крапок і дефісів; інші символи замінюються дефісом.
  • backups: за значення true вмикаються автоматичні резервні копії.
  • extra_disk_gb: розмір додаткового блокового диска NVMe. Вкажіть одне зі значень sizes_gb з каталогу (50, 100, 250, 500, 1000).
  • ddos_protection: за значення true вмикається захист від DDoS.

Вартість опцій додається до місячної ціни сервера й показується в полі monthly відповіді, а в кожну дату оплати сервер автоматично продовжується на ту саму суму. В одному акаунті можна створити до 10 серверів.

Крок 5. Перевірте статус і підключіться

Новий сервер починає в статусі creating, а коли все готово, переходить у running, і заповнюється адреса ipv4. Цикл нижче кожні 10 секунд перевіряє статус і, коли він стане running, виводить IP. Замініть код сервера на код свого сервера.

Термінал
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

Статус може бути одним із таких: creating, running, stopped, rebooting, installing, suspended або check. suspended означає, що сервер був призупинений через непродовження в дату оплати, а check означає, що ми перевіряємо результат налаштування сервера. Як тільки з'явиться IP, підключіться за допомогою ssh root@IP. Як підключитися, описано в посібнику першого входу.

Крок 6. Живлення, продовження, видалення

Термінал
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: вмикає зупинений (stopped) сервер.
  • stop, reboot: вимикає або перезавантажує робочий (running) сервер.
  • renew: оплачує ще 1, 3, 6 або 12 місяців одразу. Призупинений сервер також повертається до роботи з цим запитом.
  • DELETE: видаляє сервер і диск та повертає {"state": "deleted"}. Залишок уже оплаченого місяця не повертається.

Якщо надіслати дію, недоступну в поточному статусі, повернеться 409 wrong_state. Наприклад, так буде, якщо надіслати start уже ввімкненому серверу. Перевстановлення й створення нового пароля root виконуються на сторінці сервера. Порядок описано в посібнику з перевстановлення.

Той самий порядок на Python

Той самий сценарій у вигляді скрипта на Python виглядає так. Використовується бібліотека 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)

Часті коди помилок

  • 401 unauthorized: ключа немає або він неправильний. Перевірте, що заголовок має вигляд Authorization: Bearer hvp_....
  • 403 not_allowed: стає доступним після підтвердження першої оплати.
  • 400 bad_request: неправильне ім'я поля чи значення. Використовуйте коди точно як у каталозі.
  • 402 not_enough_balance: сума оплати менше $25. Надішліть запит знову з мінімум $25.
  • 409 limit: досягнуто межі кількості серверів в акаунті.
  • 409 not_created: сервер не вдалося створити, і плата повертається на кредит вашого акаунта.
  • 202 checking: ми перевіряємо результат налаштування сервера. Не надсилайте той самий запит повторно; перевірте список серверів. Сервер буде завершений, або плата повернеться на кредит вашого акаунта.
  • 404 not_found: такого коду сервера чи адреси немає у вашому акаунті.
  • 409 wrong_state: ця дія недоступна в поточному статусі.
  • 429 rate_limited: досягнуто межі запитів на хвилину. Трохи зачекайте й надішліть знову.

Усі ендпоінти, поля відповідей і приклади зібрано в документації API. Що можна робити через API і для чого, дивіться на сторінці VPS API.

Корисні посібники на тему

Налаштування, які варто зробити слідом за цим посібником.

Усі посібники