所有系统运行正常
技术支持
中文
语言

API 参考

CheapServ API v1：Bearer 认证、套餐与机房位置接口、订购服务器、发起充值、速率限制、示例和错误码。

CheapServ API 是一套小巧的 JSON API，覆盖您可能需要自动化的各项操作：查询套餐和机房位置、用余额订购服务器、读取您的服务器信息，以及创建并跟踪充值。它和控制面板用的是同一套接口，背后没有任何隐藏功能。

基础 URL
https://cheapserv.com/v1
格式
请求体和响应均为 JSON，UTF-8 编码
认证
Authorization: Bearer cs_…
速率限制
每个密钥每分钟 120 次请求

认证

在账户 → API 中生成密钥。完整密钥以 cs_ 开头，只会显示一次，请将其保存到您的密钥管理工具中。每个需要认证的请求，都要通过 Authorization 请求头携带该密钥：

curl https://cheapserv.com/v1/account \
  -H "Authorization: Bearer cs_0038063…"

密钥拥有账户的全部权限。密钥一旦泄露，请立即在控制面板中撤销；撤销自下一次请求起生效。GET /v1/plans 和 GET /v1/locations 是公开接口，无需密钥。

速率限制

每个密钥每分钟最多可发起 120 次请求。每个响应都带有 X-RateLimit-Limit 和 X-RateLimit-Remaining 响应头；额度用尽后，API 会返回 429，错误码为 rate_limited。轮询充值状态的间隔请不要短于 10 秒，因为充值状态只会随网络确认而变化。

错误

错误以 JSON 对象的形式返回，包含稳定的错误码和便于阅读的说明信息：

{"error":{"code":"validation","message":"The hostname is invalid."}}
HTTP错误码含义
400validation字段缺失或无效，错误信息中会指明具体字段（充值金额低于 $25 或高于 $5,000，或币种不受支持时，也会返回此错误）
401unauthorized密钥缺失、无法识别或已被撤销
402insufficient_balance余额不足以支付该订单，详见 POST /v1/servers
404not_found接口不存在，或该对象不属于您
429rate_limited最近一分钟内请求超过 120 次，或短时间内创建的充值地址过多
503orchestrator_down支付网络未响应；未创建任何内容，请稍后重试

GET /v1/plans

公开接口。按产品分组返回所有套餐，并附带实时库存。下单时请使用 slug。

curl https://cheapserv.com/v1/plans
{
  "vps": [
    {"slug":"vps-4","name":"VPS-4","monthly_usd":6.99,"stock":"in_stock",
     "specs":{"vcpu":"4","ram":"8 GB","nvme":"160 GB","traffic":"12 TB"}},
    {"slug":"hf-2","name":"HF-2","monthly_usd":12.39,"stock":"low",
     "specs":{"cores":"2","ram":"8 GB","nvme":"120 GB","traffic":"8 TB"}}
  ],
  "dedicated": [ {"slug":"ds-9950x","name":"DS-9950X","monthly_usd":239, "stock":"in_stock","specs":{"cpu":"AMD Ryzen 9 9950X", "ram":"192 GB","storage":"2× 4 TB NVMe Gen4","net":"1 Gbps unmetered"}} ],
  "gpu": [ {"slug":"h100-sxm","name":"H100 SXM","monthly_usd":979,"stock":"in_stock","specs":{"vram":"80 GB HBM3","vcpu":"32","ram":"256 GB","nvme":"2 TB","net":"10 Gbps"}} ],
  "rdp": [ {"slug":"rdp-4","name":"RDP-4","monthly_usd":15.19,"stock":"in_stock","specs":{"vcpu":"4","ram":"8 GB","nvme":"160 GB","os":"Windows Server 2022/2025"}} ]
}

stock 的取值为 in_stock、low（库存不超过四台）或 sold_out。订购已售罄的套餐会返回 validation 错误。VPS 分组包含全部三条产品线；以 hf- 开头的 slug 是高频型套餐，以 st- 开头的是存储型套餐。

GET /v1/locations

公开接口。列出全部六个节点，以及每个节点可承载的产品。套餐是否可用，以产品列表为准：vps_hf 和 vps_storage 与 vps 分开列出。

curl https://cheapserv.com/v1/locations
[
  {"code":"fra","city":"Frankfurt","country":"DE","hub":true,
   "products":["vps","vps_hf","vps_storage","dedicated","gpu","rdp"]},
  {"code":"hel","city":"Helsinki","country":"FI","hub":false,
   "products":["vps","vps_hf","vps_storage","dedicated","rdp"]}
]

GET /v1/account

curl https://cheapserv.com/v1/account \
  -H "Authorization: Bearer $CS_KEY"
{"email":"[email protected]","balance_usd":142.50,"created_at":"2026-09-05T14:40:12Z"}

GET /v1/servers

返回您的服务器，最新的排在最前。每个服务器对象都包含开通时分配的地址和下一次续费日期。

curl https://cheapserv.com/v1/servers \
  -H "Authorization: Bearer $CS_KEY"
[
  {"id":1041,"hostname":"web-01","product":"vps","plan":"vps-4","plan_name":"VPS-4",
   "location":"ams","image":"debian-13-12","ipv4":"198.51.100.86","ipv6":"2001:db8:2:411::1",
   "status":"active","rescue":false,"backups":false,"monthly_usd":6.99,
   "renews_at":"2026-10-05 14:41:03","created_at":"2026-09-05 14:41:03"}
]

status 的取值为 provisioning（付款后约 60 秒内）、active、stopped、rebooting、reinstalling、starting、stopping、suspended 或 cancelled。

POST /v1/servers

创建订单，并用您的预付余额支付。余额足以支付套餐价格时，服务器会立即创建并开始开通，约 60 秒内上线；余额不足时则不会创建任何内容，API 会返回 402 和缺少的金额，请先充值，再重新提交订单。

字段类型必填说明
productstring是vps、dedicated、gpu 或 rdp
planstring是来自 /v1/plans 的套餐 slug
locationstring是fra、ams、hel、nyc、lax 或 sin
imagestring否镜像 slug；默认使用该产品的第一个镜像
hostnamestring否小写字母、数字、连字符和点；最长 63 个字符；省略时自动生成
qtyinteger否VPS 和 RDP 为 1 到 10，其他产品固定为 1
 
curl -X POST https://cheapserv.com/v1/servers \
  -H "Authorization: Bearer $CS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"vps","plan":"vps-4","location":"fra",
       "image":"ubuntu-24-04-22-04","hostname":"web-01","qty":1}'
HTTP/2 201
{"order_id":1041,"paid":true,
 "servers":[
   {"id":1041,"hostname":"web-01","product":"vps","plan":"vps-4","plan_name":"VPS-4",
    "location":"fra","image":"ubuntu-24-04-22-04","ipv4":"198.51.100.49","ipv6":"2001:db8:1:411::1",
    "status":"provisioning","rescue":false,"backups":false,"monthly_usd":6.99,
    "renews_at":"2026-10-05 14:41:03","created_at":"2026-09-05 14:41:03"}
 ]}

余额不足时：

HTTP/2 402
{"error":{"code":"insufficient_balance","message":"Your balance does not cover this order. Top up first."},
 "balance_usd":4.20,"total_usd":6.99,"missing_usd":2.79,
 "topup_url":"https://cheapserv.com/account/topup"}

所选机房位置未提供的套餐、已售罄的套餐或无效的主机名，都会返回 400 validation。当 qty 大于 1 时，每台机器返回一个服务器对象，主机名依次加上后缀 -1、-2，以此类推。

Slug 命名规则

套餐 slug 由小写的套餐名称生成，其中空格替换为连字符，× 替换为 x：vps-4、hf-2、st-1、ds-9950x、rtx-5090、h100-sxm、8x-h100-sxm、rdp-4、rdp-gpu。镜像 slug 由小写的镜像名称和版本号生成，其中每一段连续的非字母数字字符都替换为一个连字符：ubuntu-24-04-22-04、debian-13-12、rocky-linux-10-9、windows-server-2022-2025。

GET /v1/topups

列出您的充值记录，最新的排在最前，每条记录是一个充值对象（见下文）。

curl https://cheapserv.com/v1/topups \
  -H "Authorization: Bearer $CS_KEY"

POST /v1/topups

创建一笔充值，并返回其充值信息：唯一的充值地址、精确的加密货币金额，以及 30 分钟的有效期。金额以美元计，范围为 $25 至 $5,000。币种代码：BTC、ETH、XMR、USDTTRC（TRC-20 网络上的泰达币）和 USDT（ERC-20 网络上的泰达币）。第一个地址仍在有效期内时，如果用相同的币种和金额再创建一笔充值，将直接返回已有的那一笔，而不会生成新地址。

curl -X POST https://cheapserv.com/v1/topups \
  -H "Authorization: Bearer $CS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":50,"coin":"USDTTRC"}'
HTTP/2 201
{"ref":"cs-k7m2qp4xh9b1zt3v6nwd","amount_usd":50,"bonus_usd":0,"coin":"USDTTRC","status":"pending",
 "deposit_address":"TX3…","deposit_amount":"50.01","deposit_network":"TRX","deposit_tag":null,
 "received":null,"missing":null,"txid":null,
 "expires_at":"2026-09-05 15:11:03","paid_at":null,"created_at":"2026-09-05 14:41:03",
 "url":"https://cheapserv.com/account/topup/cs-k7m2qp4xh9b1zt3v6nwd"}

请把确切的 deposit_amount（以 coin 计）发送到 deposit_address（deposit_network 网络），并在 expires_at 之前完成。金额低于 $25 或高于 $5,000，或币种不受支持，会返回 400 validation；短时间内创建过多地址，会返回 429 rate_limited；若支付网络未响应，则返回 503 orchestrator_down，且不会创建任何内容。

GET /v1/topups/{ref}

返回一笔充值，并从支付网络刷新其状态。status 的取值为 pending（等待充值）、confirming、underpaid（此时 received 和 missing 会给出加密货币金额；请将 missing 的数额发送到同一地址）、completed（余额已入账）、expired、cancelled 或 error。已过期的充值无法恢复，请重新创建一笔。

curl https://cheapserv.com/v1/topups/cs-k7m2qp4xh9b1zt3v6nwd \
  -H "Authorization: Bearer $CS_KEY"
{"ref":"cs-k7m2qp4xh9b1zt3v6nwd","amount_usd":50,"bonus_usd":0,"coin":"USDTTRC","status":"completed",
 "deposit_address":"TX3…","deposit_amount":"50.01","deposit_network":"TRX","deposit_tag":null,
 "received":null,"missing":null,"txid":"7c1e…",
 "expires_at":"2026-09-05 15:11:03","paid_at":"2026-09-05 14:52:40","created_at":"2026-09-05 14:41:03",
 "url":"https://cheapserv.com/account/topup/cs-k7m2qp4xh9b1zt3v6nwd"}

示例：充值、等待到账，再下单

#!/bin/sh
set -e
API=https://cheapserv.com/v1
ref=$(curl -sf -X POST "$API/topups" \
  -H "Authorization: Bearer $CS_KEY" -H "Content-Type: application/json" \
  -d '{"amount_usd":50,"coin":"USDTTRC"}' | jq -r .ref)
echo "top-up $ref — send the deposit shown at $API/topups/$ref"
while :; do
  st=$(curl -sf "$API/topups/$ref" -H "Authorization: Bearer $CS_KEY" | jq -r .status)
  [ "$st" = completed ] && break
  [ "$st" = expired ] && { echo expired; exit 1; }
  sleep 10
done
curl -sf -X POST "$API/servers" \
  -H "Authorization: Bearer $CS_KEY" -H "Content-Type: application/json" \
  -d '{"product":"vps","plan":"hf-2","location":"nyc","hostname":"db-01"}' | jq '.servers[]'

版本管理

路径前缀 /v1 即版本号。在同一版本内，响应中的字段只会新增，绝不会删除或重命名，因此请忽略您不认识的字段。不兼容的变更将以 /v2 的形式发布，两个版本会并行运行至少六个月，并在状态页上公告，同时通过电子邮件通知每一位持有 API 密钥的账户。

上一篇网络

本页有遗漏或错误？提交工单，告诉我们。