客户 API · V1 公测版
面向 VPS 与独立服务器的
REST API
用代码管理您的服务器：订购和销毁按小时 VPS，执行电源操作和重装系统，制作并部署您自己的镜像，以及用账户余额支付账单。
X-ZoneServers 客户 API（v1，公测版）通过 HTTPS 提供 92 个操作，配有 OpenAPI 3.0 规范和可限定权限范围的 API 密钥，默认限额为每个密钥每小时 1,000 次请求。所有账户均可使用，不收取额外费用。
92 个 API 操作1,000 次请求/小时（每个密钥）
第一次 API 调用
在客户中心的 Profile → API Keys 中创建密钥，然后向 API 询问“我是谁”。
curl https://my.x-zoneservers.com/api/v1/ \
-H "Authorization: Bearer $XZ_API_KEY"
{ "success": true,
"data": {
"version": "1",
"key": { "scopes": ["read", "services"] },
"rate_limit": { "limit": 1000, "remaining": 999 }
} }01功能
可自动化的操作
API 覆盖服务器从下单到账单的完整生命周期，权限与客户中心完全一致。
部署与销毁
以按小时或按月计费订购 VPS，为首次启动传入 cloud-init user-data 和 SSH 密钥，任务完成后即可删除。服务器一经删除，按小时计费立即停止。
电源、重装与统计
启动、停止、重启和重装您的 VPS，重置 root 密码，并在您的监控脚本中读取用量和流量统计。
自定义镜像
将 VPS 制作为镜像（每个账户最多 3 个），或注册您自己的 qcow2 或 raw 镜像（通过 SHA-256 校验），并用它部署新服务器。
账单与用量
读取账户余额和本月按小时计费的费用，列出账单和形式发票，并用余额支付——适合用于成本仪表板和预算告警。
附加服务与升级
为现有服务购买附加服务（例如额外的 IP 地址），或将其升级到更大的套餐，全程无需打开客户中心。
项目与权限范围密钥
将服务器按项目分组，并签发仅绑定单个项目的密钥，让预发布环境的密钥永远无法查看或操作生产环境。
02工作原理
示例：为单次 CI 任务创建按小时 VPS
创建一台干净的构建机，运行流水线，然后删除——只为它存在的小时数付费。
按小时计费的服务直接从账户余额扣费，而不是开具账单，因此请保持账户有余额。每次下单都请附带 Idempotency-Key 请求头：这样超时的请求可以安全重试，而不会创建第二台服务器。
1. 选择套餐：列出产品及其小时价和月价。
curl https://my.x-zoneservers.com/api/v1/products \
-H "Authorization: Bearer $XZ_API_KEY"2. 以按小时计费下单，并附上首次启动脚本和您的 SSH 密钥。
curl -X POST https://my.x-zoneservers.com/api/v1/orders \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Idempotency-Key: ci-run-4812" \
-H "Content-Type: application/json" \
-d '{"productId": "<plan-id>", "billingCycle": "hourly",
"hostname": "ci-4812.example.com", "location": "<location>",
"configOptions": {"os_image_id": "<image-id>",
"ssh_keys": ["ssh-ed25519 AAAA... ci@runner"],
"user_data": "#!/bin/sh\n/opt/ci/run-pipeline.sh"}}'3. 任务完成后删除服务器，计费立即停止。
curl -X DELETE https://my.x-zoneservers.com/api/v1/vps/<vps-id> \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"immediate": true}'03API
专为脚本与 AI 智能体打造
当点击按钮的是程序而不是人时，可预测的行为比端点数量更重要。
权限范围密钥
每个密钥只拥有您授予的权限范围（read、services、orders、billing、destructive），还可选配 IP 允许列表和到期日期。
公开的速率限制
默认每个密钥每小时 1,000 次请求，并通过 X-RateLimit 响应头告知；电源和重装操作按服务器设有短暂的冷却时间。
安全重试
订单支持 Idempotency-Key，每次拒绝都会返回机器可读的错误码，让自动化程序能区分可重试的失败与真正的失败。
机器可读的文档
提供供客户端生成器使用的 OpenAPI 3.0 规范，以及编程助手和 AI 智能体可直接读取的纯 Markdown 指南。
04相关内容
要向您自己的客户销售服务器？
此客户 API 用于自动化管理您自己的账户。如需以您自己的品牌转售，请加入分销商计划并改用分销商 API：按用量分级的批发价格、HMAC 签名请求、Webhook、绑定客户的密钥，以及您的客户无需在我们这里注册账户即可打开的控制台链接。
05常见问题
API 常见问题
关于 X-ZoneServers 自动化的常见问题。
X-ZoneServers 提供 API 吗？
提供。位于 https://my.x-zoneservers.com/api/v1 的客户 API（v1）是一个基于 HTTPS 的 REST API，提供 92 个操作，涵盖 VPS、独立服务器、订单、附加服务、升级、账单、SSH 密钥和自定义镜像。它目前处于公测阶段：已足够稳定，可以在其上进行开发，但端点和响应结构仍可能变化。
API 访问免费吗？
免费。所有账户均包含 API 访问权限，不收取额外费用；您只需为订购的服务器和附加服务付费，价格与官网和客户中心完全相同。
可以通过 API 创建和删除按小时计费的 VPS 吗？
可以。下单时将计费周期设为按小时，可选附带 cloud-init user-data 和 SSH 密钥，不再需要时删除该 VPS 即可。按小时计费的服务从账户余额扣费，一经删除即停止计费。
API 支持独立服务器吗？
部分支持。对于独立服务器，API 涵盖订购、附加服务、账单和服务详情。电源控制、操作系统重装和密码重置功能，无论通过 API 还是客户中心，都不适用于独立服务器。
如何进行身份验证？
在客户中心的 Profile → API Keys 中创建 API 密钥，并将其作为 Bearer 令牌发送。创建时选择其权限范围，还可以将其限制为特定 IP 地址或设置到期日期。密钥仅显示一次，可随时在客户中心吊销。
是否提供 OpenAPI 或 Swagger 规范？
提供。我们在 https://my.x-zoneservers.com/api/v1/openapi.json 发布了完整的 OpenAPI 3.0 规范，同时提供渲染好的文档和 Markdown 使用指南。