Mula pantas API VPS, mencipta kunci API dan pelayan pertama

Langkah 2. Pengesahan dan permintaan pertama

Semua permintaan dihantar ke alamat asas https://helpervps.com/api/v1, dengan header Authorization: Bearer API_KEY. Sebagai permintaan pertama, dapatkan senarai pelayan anda. Jika belum ada pelayan, senarai kosong [] dikembalikan.

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

Setiap akaun boleh menghantar sehingga 300 permintaan seminit, dan penciptaan pelayan sehingga 10 kali setiap 10 minit. Untuk permintaan berulang yang menyemak status, selang beberapa saat sudah memadai. Semua respons dalam JSON, dan jika berlaku ralat, respons berbentuk {"error": "kod"} dikembalikan bersama kod status.

Langkah 3. Pilih spesifikasi, lokasi dan imej

Semua nilai yang digunakan semasa mencipta pelayan datang dari katalog. GET /catalog mengembalikan spesifikasi (plans), lokasi (locations), imej (images) dan pilihan tambahan (addons) yang dijual sekali gus. Jika ada jq, lebih mudah memilih bahagian yang diperlukan sahaja.

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 spesifikasi: seperti s1 dan s2, menunjukkan jenis dan saiz. type ialah basic (SSD standard), fast (NVMe berprestasi tinggi), cpu (CPU khusus) atau mem (memori tinggi). monthly ialah kadar bulanan dalam dolar AS.
• Kod lokasi: nama bandar seperti frankfurt, singapore dan seoul.
• Kod imej: sistem pengendalian seperti ubuntu-24-04, debian-13 dan almalinux-10, serta aplikasi seperti app-docker dan app-wordpress.
• Pilihan tambahan: peratusan sandaran automatik, saiz dan kadar setiap GB cakera tambahan, serta kadar perlindungan DDoS. Pilihan yang tidak dijual dihantar sebagai null.

Jika belum ada, pasang jq dengan apt install -y jq dalam Ubuntu atau brew install jq dalam Mac. Senarainya sama dengan yang dipilih di skrin, jadi lebih mudah dilihat bersama perbezaan setiap spesifikasi di halaman harga.

Langkah 4. Mencipta pelayan

Hantar pelan, lokasi, imej dan nama sebagai JSON ke POST /servers. Bayar untuk tempoh pertama pelan yang dipilih dan penciptaan pelayan akan bermula.

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

Jika berjaya, maklumat pelayan dikembalikan bersama kod status 201. id ialah kod pelayan berbentuk S-XXXX-XXXX-XXXX, dan kod ini digunakan dalam semua permintaan seterusnya. root_password hanya ada sekali dalam respons ini, jadi terus simpan. Kata laluan juga boleh dilihat di halaman pelayan selama 7 hari.

• label: nama pelayan. Gunakan huruf Rumi, nombor, titik dan sempang hingga 40 aksara, dan aksara lain ditukar kepada sempang.
• backups: jika true, sandaran automatik diaktifkan.
• extra_disk_gb: saiz cakera blok NVMe tambahan. Masukkan salah satu nilai sizes_gb dalam katalog (50, 100, 250, 500, 1000).
• ddos_protection: jika true, perlindungan DDoS diaktifkan.

Kos pilihan digabungkan dengan kadar bulanan pelayan dan dipaparkan dalam monthly pada respons, kemudian diperbaharui automatik dengan jumlah yang sama setiap tarikh bil. Setiap akaun boleh mencipta sehingga 10 pelayan.

Langkah 5. Semak status dan log masuk

Pelayan baharu bermula dengan status creating, menjadi running apabila siap, dan alamat ipv4 diisi. Gelung di bawah menyemak status setiap 10 saat dan memaparkan IP apabila sudah running. Tukar kod pelayan kepada kod pelayan anda.

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 adalah salah satu daripada creating, running, stopped, rebooting, installing, suspended atau check. suspended bermaksud pelayan dihentikan sementara kerana tidak diperbaharui pada tarikh bil, dan check bermaksud kami sedang menyemak hasil penyediaan pelayan. Setelah IP muncul, sambungkan dengan ssh root@IP. Cara menyambung ada dalam panduan log masuk pertama.

Langkah 6. Kuasa, pembaharuan dan pemadaman

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: menghidupkan pelayan yang berhenti (stopped).
• stop, reboot: mematikan atau memulakan semula pelayan yang sedang berjalan (running).
• renew: membayar untuk 1, 3, 6 atau 12 bulan lagi sekarang. Pelayan yang digantung (suspended) juga akan hidup semula dengan permintaan ini.
• DELETE: memadam pelayan dan cakeranya lalu mengembalikan {"state": "deleted"}. Baki tempoh bulan yang telah dibayar tidak dibayar balik.

Jika menghantar tindakan yang tidak boleh dilakukan dalam status semasa, 409 wrong_state dikembalikan. Contohnya apabila menghantar start kepada pelayan yang sudah hidup. Pemasangan semula dan penjanaan kata laluan root baharu dibuat di halaman pelayan. Urutannya ada dalam panduan pasang semula.

Menjalankan urutan yang sama dengan Python

Aliran yang sama jika ditulis sebagai skrip Python kelihatan seperti ini. Menggunakan pustaka requests (pip install requests).

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)

Kod ralat yang kerap dilihat

• 401 unauthorized: kunci tiada atau salah. Semak sama ada header berbentuk Authorization: Bearer hvp_....
• 403 not_allowed: dibuka setelah pembayaran pertama anda disahkan.
• 400 bad_request: nama atau nilai medan salah. Gunakan kod tepat seperti nilai katalog.
• 402 not_enough_balance: jumlah pembayaran adalah di bawah $25. Hantar semula dengan sekurang-kurangnya $25.
• 409 limit: bilangan pelayan yang boleh dicipta dalam akaun telah dicapai.
• 409 not_created: pelayan tidak dapat dicipta, dan bayaran akan dikembalikan ke kredit akaun anda.
• 202 checking: kami sedang menyemak hasil penyediaan pelayan. Jangan hantar permintaan yang sama lagi; semak senarai pelayan anda. Pelayan akan disiapkan atau bayaran akan dikembalikan ke kredit akaun anda.
• 404 not_found: kod pelayan atau alamat yang tiada dalam akaun anda.
• 409 wrong_state: tindakan yang tidak boleh dilakukan dalam status semasa.
• 429 rate_limited: had permintaan seminit telah dicapai. Tunggu sebentar kemudian hantar semula.

Semua endpoint, medan respons dan contoh dihimpunkan dalam dokumentasi API. Perkara yang boleh dilakukan dengan API dan kegunaannya boleh dilihat di halaman VPS API.