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