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": "代碼"} 的形式返回。

第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 頁面檢視。