VPS API 快速入門：建立 API 金鑰及首部伺服器

第 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、Mac 以 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）。

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 頁面查看。