HELPER VPS

Szybki start VPS API: tworzenie klucza API i pierwszego serwera

API HELPER VPS to REST API wymieniające JSON przez HTTPS. Jednym kluczem pobierzesz konfiguracje, utworzysz serwery, zarządzisz zasilaniem, przedłużysz je i usuniesz. Przejdź drogę od pierwszego żądania do utworzenia i usunięcia jednego serwera.

Krok 1. Utwórz klucz API

Klucz API możesz utworzyć po pierwszej płatności. Zobacz poradnik płatności USDT, aby dowiedzieć się, jak płacić.

  • Kliknij „Utwórz klucz API” w menu kluczy API na koncie.
  • Klucz zaczynający się od hvp_ pokazywany jest tylko raz. Od razu go skopiuj i zapisz w menedżerze haseł.
  • Na ekranie zostają tylko ostatnie znaki klucza, aby było widać, który klucz jest używany.
  • Po kliknięciu „Utwórz nowy klucz” pojawia się nowy klucz, a stary od razu przestaje działać.

Klucz daje dostęp do całego konta, więc używaj go przez zmienną środowiskową, aby nie trafił do repozytorium kodu ani na udostępniany ekran. Przykłady w tym poradniku zaczynają się od zapisania klucza w zmiennej w terminalu.

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

Krok 2. Uwierzytelnianie i pierwsze żądanie

Wszystkie żądania wysyłasz na adres bazowy https://helpervps.com/api/v1 z nagłówkiem Authorization: Bearer klucz. Pierwszym żądaniem pobierz listę swoich serwerów. Jeśli nie masz serwerów, wróci pusta lista [].

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

Z jednego konta możesz wysyłać do 300 żądań na minutę, a tworzyć serwery do 10 razy w ciągu 10 minut. Dla powtarzanych żądań sprawdzania statusu wystarczy odstęp kilku sekund. Wszystkie odpowiedzi przychodzą w JSON, a w razie błędu wracają z kodem statusu w postaci {"error": "code"}.

Krok 3. Wybierz konfigurację, region i obraz

Wszystkie wartości do utworzenia serwera pochodzą z katalogu. GET /catalog zwraca naraz dostępne konfiguracje (plans), regiony (locations), obrazy (images) i opcje dodatkowe (addons). Z jq wygodnie wybierać tylko potrzebne części.

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'
  • Kod konfiguracji: na przykład s1 lub s2, oznacza typ i rozmiar. type to basic (standardowy SSD), fast (wydajny NVMe), cpu (dedykowany CPU) i mem (duża ilość pamięci). monthly to cena miesięczna w dolarach amerykańskich.
  • Kod regionu: nazwa miasta, na przykład frankfurt, singapore lub seoul.
  • Kod obrazu: systemy operacyjne, na przykład ubuntu-24-04, debian-13 lub almalinux-10, oraz aplikacje, na przykład app-docker lub app-wordpress.
  • Opcje dodatkowe: udział kosztu automatycznych kopii, rozmiary dodatkowego dysku i cena za GB, cena ochrony DDoS. Niedostępne opcje przychodzą jako null.

Jeśli nie masz jq, w Ubuntu zainstaluj go poleceniem apt install -y jq, w macOS brew install jq. To ta sama lista co w interfejsie, więc różnice między konfiguracjami wygodnie oglądać razem ze stroną cen.

Krok 4. Utwórz serwer

Wyślij plan, lokalizację, obraz i nazwę jako JSON do POST /servers. Opłać pierwszy okres wybranego planu, a rozpocznie się tworzenie serwera.

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"}'

Po powodzeniu wróci kod statusu 201 i dane serwera. id to kod serwera w postaci S-XXXX-XXXX-XXXX, używany we wszystkich kolejnych żądaniach. root_password przychodzi w tej odpowiedzi tylko raz, więc od razu go zapisz. Na stronie serwera też jest widoczny przez 7 dni.

  • label: nazwa serwera. Do 40 znaków z liter łacińskich, cyfr, kropek i myślników; inne znaki są zamieniane na myślnik.
  • backups: wartość true włącza automatyczne kopie zapasowe.
  • extra_disk_gb: rozmiar dodatkowego dysku blokowego NVMe. Podaj jedną z wartości sizes_gb z katalogu (50, 100, 250, 500, 1000).
  • ddos_protection: wartość true włącza ochronę DDoS.

Koszt opcji doliczany jest do miesięcznej ceny serwera i widoczny w polu monthly odpowiedzi, a w każdej dacie płatności serwer automatycznie przedłuża się za tę samą kwotę. Na jednym koncie utworzysz do 10 serwerów.

Krok 5. Sprawdź status i połącz się

Nowy serwer zaczyna w statusie creating, a gdy wszystko jest gotowe, przechodzi w running i wypełnia się adres ipv4. Pętla poniżej co 10 sekund sprawdza status i, gdy będzie running, wyświetla IP. Zastąp kod serwera kodem swojego serwera.

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

Status to jeden z następujących: creating, running, stopped, rebooting, installing, suspended lub check. suspended oznacza, że serwer został wstrzymany z powodu braku odnowienia w dacie płatności, a check oznacza, że sprawdzamy wynik konfiguracji serwera. Gdy pojawi się IP, połącz się za pomocą ssh root@IP. Jak się połączyć, opisuje poradnik pierwszego logowania.

Krok 6. Zasilanie, przedłużenie, usuwanie

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: włącza zatrzymany (stopped) serwer.
  • stop, reboot: wyłącza lub restartuje działający (running) serwer.
  • renew: opłaca teraz kolejne 1, 3, 6 lub 12 miesięcy. Wstrzymany serwer również zostaje przywrócony tym żądaniem.
  • DELETE: usuwa serwer i dysk i zwraca {"state": "deleted"}. Pozostała część opłaconego miesiąca nie jest zwracana.

Jeśli wyślesz działanie niedostępne w bieżącym statusie, wróci 409 wrong_state. Tak będzie na przykład, gdy wyślesz start do już włączonego serwera. Reinstalację i tworzenie nowego hasła root wykonujesz na stronie serwera. Kolejność opisuje poradnik reinstalacji.

Ta sama kolejność w Pythonie

Ten sam scenariusz jako skrypt w Pythonie wygląda tak. Używa biblioteki 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)

Częste kody błędów

  • 401 unauthorized: brak klucza lub klucz jest błędny. Sprawdź, czy nagłówek ma postać Authorization: Bearer hvp_....
  • 403 not_allowed: dostępne po potwierdzeniu pierwszej płatności.
  • 400 bad_request: błędna nazwa pola lub wartość. Używaj kodów dokładnie jak w katalogu.
  • 402 not_enough_balance: kwota płatności jest niższa niż $25. Wyślij ponownie z co najmniej $25.
  • 409 limit: osiągnięto limit liczby serwerów na koncie.
  • 409 not_created: serwer nie mógł zostać utworzony, a opłata trafia na saldo konta.
  • 202 checking: sprawdzamy wynik konfiguracji serwera. Nie wysyłaj ponownie tego samego żądania; sprawdź listę serwerów. Serwer zostanie ukończony lub opłata zostanie zwrócona na saldo konta.
  • 404 not_found: takiego kodu serwera lub adresu nie ma na Twoim koncie.
  • 409 wrong_state: to działanie jest niedostępne w bieżącym statusie.
  • 429 rate_limited: osiągnięto limit żądań na minutę. Poczekaj chwilę i wyślij ponownie.

Wszystkie endpointy, pola odpowiedzi i przykłady zebraliśmy w dokumentacji API. Co można robić przez API i do czego, zobaczysz na stronie VPS API.

Przydatne poradniki na ten temat

Ustawienia, które warto zrobić po tym poradniku.

Wszystkie poradniki