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.

Полезные руководства по теме

Настройки, которые стоит сделать вслед за этим руководством.

Все руководства