HELPER VPS

VPS API 文件：建立及管理伺服器的 REST API

這是以 HTTPS 收發 JSON 的 REST API。只要在 Authorization 標頭傳送一個 API 金鑰，便可用程式完成帳戶畫面的所有工作，由查詢規格、建立伺服器、電源管理、續期到刪除。每個帳戶每分鐘最多可發送 300 個請求。

API 可以做的事

API 適合管理多部伺服器或自動化部署時使用。讀取方案、地區及映像清單；建立伺服器時，付款處理後伺服器即建立。規則與網頁相同，以 API 建立的伺服器亦會顯示在帳戶的伺服器清單中。

初次使用，請參閱 API 快速入門指南，按次序由建立金鑰做到建立首部伺服器。本頁是集合所有端點及欄位的參考文件。

基本位址

所有請求都在以下位址後加上路徑發送。請求及回應內容全部為 JSON（UTF-8）。

https://helpervps.com/api/v1

認證

傳送標頭 Authorization: Bearer YOUR_API_KEY。首次付款後可在帳戶的 API 金鑰選單建立金鑰，金鑰以 hvp_ 開頭。金鑰只在建立後即時完整顯示一次；建立新金鑰後，舊金鑰即時失效。

curl https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

請求限額

所有請求每個帳戶每分鐘 300 次
建立伺服器（POST /servers）每個帳戶每 10 分鐘 10 次
帳戶伺服器數目最多 10 部

伺服器編號

伺服器以 S-7K2M-9QX4-HB3T 這類伺服器編號區分，而非數字編號。把伺服器清單或建立回應中的 id 值直接放入路徑便可，不分大小寫。

GET /catalog

一次過回傳在售的規格（plans）、地區（locations）、映像（images）及額外選項（addons）。建立伺服器時填入的代碼全部來自這裡。monthly 為美元月費，不出售的選項會以 null 回傳。額外硬碟的 monthly_per_gb 顯示至小數點後第三位。

請求範例

curl https://helpervps.com/api/v1/catalog \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "plans": [
    { "code": "s2", "type": "basic", "vcpu": 1, "ram_mb": 2048, "disk_gb": 50, "transfer_tb": 2, "monthly": "2.48" }
  ],
  "locations": ["frankfurt", "singapore", "seoul"],
  "images": ["ubuntu-24-04", "debian-13", "almalinux-10", "app-docker"],
  "addons": {
    "backups": { "percent_of_plan": 5.6 },
    "extra_disk": { "sizes_gb": [50, 100, 250, 500, 1000], "monthly_per_gb": "0.028" },
    "ddos_protection": { "monthly": "1.68" }
  }
}

GET /servers

按最近建立的次序回傳你的伺服器清單。已刪除或未能建立的伺服器不會列出。

請求範例

curl https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

[
  {
    "id": "S-7K2M-9QX4-HB3T",
    "label": "web-1",
    "state": "running",
    "ipv4": "192.0.2.15",
    "ipv6": "2001:db8::15",
    "monthly": "2.48",
    "backups": false,
    "extra_disk_gb": 0,
    "ddos_protection": false,
    "paid_until": "2026-11-18T09:00:00.000Z"
  }
]

POST /servers

建立伺服器並處理付款。直接使用方案、地區及映像的目錄代碼。label 最多 40 個英文字母、數字、點及連字號；其他字元會轉為連字號。backups、extra_disk_gb 及 ddos_protection 為可選選項。成功時回傳 201 及伺服器資料，root_password 只在此回應出現一次（帳戶的伺服器頁面亦可查看 7 日）。

請求範例

curl -X POST https://helpervps.com/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1","backups":true,"extra_disk_gb":0,"ddos_protection":false}'

回應範例

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "creating",
  "ipv4": null,
  "ipv6": null,
  "monthly": "2.61",
  "backups": true,
  "extra_disk_gb": 0,
  "ddos_protection": false,
  "paid_until": "2026-11-18T09:00:00.000Z",
  "root_password": "..."
}

GET /servers/{id}

回傳單一伺服器的狀態、位址、月費及付款到期日。新伺服器由 creating 開始，準備完成後轉為 running，並填入 ipv4 及 ipv6。每隔數秒確認一次已綽綽有餘。

請求範例

curl https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "running",
  "ipv4": "192.0.2.15",
  "ipv6": "2001:db8::15",
  "monthly": "2.61",
  "backups": true,
  "extra_disk_gb": 0,
  "ddos_protection": false,
  "paid_until": "2026-11-18T09:00:00.000Z"
}

POST /servers/{id}/start (stop, reboot)

start 開啟已停止（stopped）的伺服器，stop 及 reboot 關閉或重新啟動運行中（running）的伺服器。回應為更新後的伺服器資料。

請求範例

curl -X POST https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T/reboot \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "id": "S-7K2M-9QX4-HB3T",
  "label": "web-1",
  "state": "rebooting",
  ...
}

POST /servers/{id}/renew

立即付款以延長有效期。到期後暫停的伺服器亦可透過此請求重新啟動。

請求範例

curl -X POST https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T/renew \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "id": "S-7K2M-9QX4-HB3T",
  "state": "running",
  "paid_until": "2026-12-18T09:00:00.000Z",
  ...
}

DELETE /servers/{id}

刪除伺服器及硬碟。下個收費日起不再收費，已付月份的剩餘期間不設退款。

請求範例

curl -X DELETE https://helpervps.com/api/v1/servers/S-7K2M-9QX4-HB3T \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "id": "S-7K2M-9QX4-HB3T",
  "state": "deleted"
}

伺服器回應欄位

id伺服器編號（S-XXXX-XXXX-XXXX）。所有路徑均使用此值。
label伺服器名稱
statecreating、running、stopped、rebooting、installing、suspended、check 其中之一
ipv4, ipv6伺服器位址。準備完成前為 null
monthly連同選項的月費（美元，字串）
backups, extra_disk_gb, ddos_protection所選額外選項
paid_until到期時間（UTC，ISO 8601）。屆時伺服器可能會暫停。
root_password只在建立回應出現一次。

狀態值

creating正在建立伺服器。
running運行中，可使用 stop、reboot。
stopped已停止，以 start 開機。
rebooting正在重新啟動。
installing正在重新安裝。
suspended有效期結束後暫停。使用 renew 重新啟動。
check正在確認伺服器準備結果。伺服器會完成建立，或退款。

錯誤

出錯時會連同狀態代碼回傳 {"error": "code"} 格式的 JSON。按代碼值分流處理便可。

401 unauthorizedAPI 金鑰缺少或錯誤。
403 not_allowed首次付款後 API 即開放。
400 bad_request欄位缺少或數值錯誤。代碼請照用目錄中的值。
402 not_enough_balance完成付款後再發送。
409 limit已達帳戶可建立的伺服器數目上限。
409 not_created未能建立伺服器，付款已退款。
202 checking正在確認伺服器準備結果。請勿重複發送相同請求，請查看伺服器清單。我們會完成伺服器建立，或退款。
404 not_found你的帳戶沒有該伺服器或路徑。
409 wrong_state伺服器目前的狀態不能進行此操作。
429 rate_limited已達請求限額，請稍候再發送。

相關指引

付款透過安全的 PayGate 結帳頁面進行。您可在帳戶的伺服器頁面重新安裝及建立新 root 密碼；步驟見 重新安裝指南。

API 可以做的事及自動化範例見 VPS API 頁面，各規格月費見 收費頁面。