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 | 伺服器名稱 |
| state | creating、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": "代碼"} 格式的 JSON。按代碼值分別處理即可。
| 401 unauthorized | 缺少 API 金鑰或金鑰錯誤。 |
| 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 密碼；步驟請參閱重新安裝指南。