很多搬瓦工用户平时管理 VPS，都是直接进入 KiwiVM 面板操作。需要重启时点击 Restart，需要查看流量时打开 Main Controls，需要创建快照时进入 Snapshots 页面。对于只管理一台 VPS、偶尔才操作一次的用户来说，这种方式已经完全够用。
通过 KiwiVM API 获取 API KEY、调用接口，并实现搬瓦工 VPS 自动快照、状态监控和流量提醒。
但是，如果您希望某些操作可以自动完成，例如每天凌晨自动创建快照、定时检查 VPS 是否在线、流量快用完时自动提醒，或者手里有多台 VPS 想统一查看状态，那么每次都手动登录面板就会变得比较麻烦。这时候，KiwiVM API 就能派上用场。
API 听起来像是程序员才会用的东西，但 KiwiVM API 的使用门槛并不高。它不需要复杂的 OAuth 授权流程，也不需要安装官方 SDK。只要您准备好 VPS 对应的 VEID 和 API KEY，就可以通过 curl、Python 等方式调用接口，让脚本代替您完成一部分面板操作。
一、KiwiVM API 是什么？适合哪些用户使用？
KiwiVM 是搬瓦工 VPS 使用的控制面板。平时我们在 KiwiVM 面板里完成的很多操作，例如查看服务器状态、重启 VPS、创建快照、查看流量、重装系统、迁移机房等，本质上都可以通过后台接口完成。KiwiVM API 就是把这些操作开放给脚本或程序使用的一套接口。
您可以把 API 理解成“程序可以使用的控制按钮”。平时您是打开网页，然后用鼠标点击按钮；使用 API 之后，则是脚本向指定接口发送请求，由 KiwiVM 系统接收请求并执行相应操作。比如您想查询 VPS 状态，脚本就访问查询状态的接口；您想创建快照，脚本就访问创建快照的接口。
对于普通用户来说，KiwiVM API 并不是必须学习的内容。如果您只是偶尔重启 VPS、查看流量，直接使用面板会更简单。但如果您想定时创建快照、监控 VPS 状态、做流量提醒，或者批量管理多台 VPS，那么 API 就能减少很多重复操作。换句话说，KiwiVM API 的价值不在于替代面板，而在于让重复性的管理操作变得更省事。
如果您使用搬瓦工 VPS 运行较吃资源的应用，除了学习 API 自动化管理，也要先确认服务器配置是否够用。例如准备部署 OpenClaw 的用户，可以参考 搬瓦工VPS部署OpenClaw内存要求及VPS配置推荐，先了解内存、CPU 和套餐选择，再决定是否需要配合 API 做监控和备份。
二、使用 KiwiVM API 前的准备：VEID、API KEY 和 JSON
调用 KiwiVM API 前，您需要准备两个最重要的参数：VEID 和 API KEY。它们是 KiwiVM 用来识别 VPS 和验证权限的关键信息。没有这两个参数，接口不会知道您要操作哪台 VPS，也无法确认您是否有权限操作它。
VEID 可以理解成 VPS 在 KiwiVM 系统里的编号。它通常是一串数字，例如 1234567。如果您有多台搬瓦工 VPS，那么每台 VPS 都会有自己的 VEID，不能混用。
API KEY 可以理解成“程序版密码”。它通常以 private_ 开头，例如 private_xxxxxxxxxxxxxxxxx。API KEY 的权限很高，拥有它的人可能通过 API 对您的 VPS 执行重启、关机、重装系统、创建快照甚至执行命令等操作。因此，API KEY 一定不能公开，也不要截图发给别人，更不要上传到公开代码仓库。
除了 VEID 和 API KEY，您还会经常看到一种数据格式：JSON。KiwiVM API 的返回结果通常都是 JSON 格式。比如一次成功的查询结果可能类似下面这样：
{
"error": 0,
"ve_status": "running",
"hostname": "my-vps",
"ip_addresses": ["1.2.3.4"]
}
对于新手来说，不需要一开始就完整掌握 JSON。您只需要先记住两个点：第一，error 字段通常用来判断请求是否成功；第二，其他字段就是接口返回的具体信息，比如 VPS 状态、主机名、IP 地址、系统版本、流量数据等。
需要注意的是，示例中的字段只用于帮助理解，实际返回内容可能会因为套餐、机房、系统类型或接口更新而有所不同，最终以 API 实际返回结果为准。
三、获取 VEID 和 API KEY 的两种方法
VEID 和 API KEY 都可以在 KiwiVM 面板中查看。对于只有一台 VPS 的用户，直接进入对应 VPS 的 KiwiVM 面板查看即可；如果您有多台 VPS，也可以在搬瓦工后台批量导出相关信息。
如果您还不熟悉 KiwiVM 面板的入口位置，可以先参考 搬瓦工VPS教程：如何登录KiwiVM后台管理面板？（两种方法详解），先确认自己能够正常进入 KiwiVM 后台，再继续查找 API 页面和 API KEY。
1. 通过 KiwiVM 面板查看 VEID 和 API KEY
登录搬瓦工客户中心后，进入 Services → My Services，找到您要管理的 VPS，然后点击 KiwiVM Control Panel 进入控制面板。在 KiwiVM 左侧菜单中找到 API 相关选项，进入后点击 Show API Key，就可以看到这台 VPS 对应的 VEID 和 API KEY。
如果您怀疑 API KEY 已经泄露，或者曾经把密钥填入过不可信的第三方工具，建议立即在 KiwiVM 面板中重置 API KEY。重置后，旧的 API KEY 会失效，之前使用旧密钥的脚本也需要同步更新。
2. 批量导出多台 VPS 的 API 信息
如果您有多台搬瓦工 VPS，一台一台进入 KiwiVM 面板复制会比较麻烦。搬瓦工客户中心通常提供批量导出服务信息的功能，可以导出包含 VEID 和 API KEY 的 CSV 文件。这个方式适合需要批量管理多台 VPS 的用户。
不过需要特别注意，批量导出的 CSV 文件非常敏感。因为它里面可能包含您所有 VPS 的 API KEY，一旦泄露，风险比单个 API KEY 泄露更大。建议把它保存在本地安全位置，不要上传到公开网盘，不要发送给陌生人，也不要直接放进网站目录。
四、第一次调用 KiwiVM API：用 getServiceInfo 查询 VPS 信息
第一次使用 KiwiVM API 时，不建议直接尝试重启、重装系统或执行 Shell 命令。更稳妥的入门方式是先调用 getServiceInfo 接口。这个接口只负责查询 VPS 的基本信息，不会改变服务器状态，适合用来测试 VEID 和 API KEY 是否正确。
KiwiVM API 的基础地址是：
https://api.64clouds.com/v1/
不同的操作对应不同的接口名称。比如查询 VPS 基本信息的接口是：
getServiceInfo
如果使用 GET 方式，完整地址大概是下面这种形式：
https://api.64clouds.com/v1/getServiceInfo?veid=您的VEID&api_key=您的API_KEY
GET 方式比较直观，复制到浏览器或命令行里就能看懂。但在实际写脚本时，更推荐使用 POST 请求，因为 GET 会把 API KEY 放在 URL 里，可能被浏览器历史记录、Shell history、代理日志或服务器日志保存下来。为了减少密钥暴露，下面示例统一使用 POST。
在 Linux、macOS 或 Windows 终端中，可以使用 curl 调用接口：
VEID="YOUR_VEID"
API_KEY="YOUR_API_KEY"
curl -s -X POST "https://api.64clouds.com/v1/getServiceInfo" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}"
如果接口调用成功，您会看到一段 JSON 数据。里面可能包含 VPS 的主机名、IP 地址、操作系统、运行状态、流量使用情况等信息。第一次测试时，您重点看 error 字段即可。如果 error 等于 0，一般说明请求成功；如果不是 0，则需要查看 message 字段了解错误原因。
如果您希望返回结果更容易阅读，可以安装并使用 jq 工具格式化 JSON。如果您的 VPS 使用 Debian 或 Ubuntu，可以这样安装：
apt update && apt install -y jq
如果使用 CentOS、AlmaLinux 或 Rocky Linux，可以改用下面的命令：
yum install -y jq
或者：
dnf install -y jq
安装完成后，可以这样调用：
curl -s -X POST "https://api.64clouds.com/v1/getServiceInfo" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}" | jq
这一步的目的不是马上做复杂自动化，而是先确认您已经能正常访问 API。只要 getServiceInfo 能正常返回结果，后面再尝试创建快照、监控状态、统计流量就会容易很多。
五、KiwiVM API 常用接口分类：查询、重启、快照、备份和重装
KiwiVM API 覆盖的功能比较多，如果一上来直接看接口列表，新手很容易觉得混乱。更好的理解方式是按照使用场景来分类：您想查看服务器状态，就看信息查询类接口；您想开机、关机、重启，就看电源管理类接口；您想自动备份，就重点看快照和备份接口。
1. 信息查询接口：查看状态、流量和系统信息
信息查询类接口主要用于读取 VPS 当前状态，不会主动修改服务器配置，因此比较适合新手先学习。最常用的是 getServiceInfo，它可以返回 VPS 的基础信息，例如 IP 地址、操作系统、当前状态、流量总额和已用流量等。如果您需要更实时的信息，可以使用 getLiveServiceInfo，不过这类实时接口响应时间可能会更长。
| 接口名称 | 主要用途 |
|---|---|
getServiceInfo |
获取 VPS 基本信息，例如 IP、系统、状态、流量等 |
getLiveServiceInfo |
获取实时状态信息，可能包含更即时的运行状态和磁盘数据 |
getRawUsageStats |
获取更详细的使用统计数据 |
getAvailableOS |
查看当前 VPS 可安装的系统模板 |
getSuspensionDetails |
查询 VPS 是否存在暂停情况及相关原因 |
getAuditLog |
查看 KiwiVM 操作日志，方便排查异常操作 |
2. 电源管理接口：启动、停止和重启 VPS
电源管理类接口对应 KiwiVM 面板中的启动、停止、重启等功能。常见接口包括 start、stop、restart 和 kill。其中 restart 是重启 VPS，stop 是正常停止，start 是启动 VPS。
需要注意的是，kill 属于强制停止，类似强制断电，通常只适合 VPS 卡死、无法正常停止时使用。普通情况下不要随便调用 kill，否则可能导致未保存的数据丢失。
| 接口名称 | 主要用途 |
|---|---|
start |
启动 VPS |
stop |
正常停止 VPS |
restart |
重启 VPS |
kill |
强制停止 VPS，一般只在卡死时使用 |
例如，使用 API 重启 VPS 可以这样写：
curl -s -X POST "https://api.64clouds.com/v1/restart" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}"
3. 快照和备份接口：创建快照与恢复数据
快照和备份是 KiwiVM API 中非常实用的一类功能。比如您准备升级系统、修改网站环境、调整防火墙规则，最好在操作前先创建一个快照。这样即使后面配置改错了，也能通过快照恢复到之前的状态。
这里需要区分快照和自动备份。快照通常更适合用户在重要操作前手动创建，用来快速回滚当前 VPS 状态；自动备份则是系统按规则生成的备份记录，用户一般不能像快照那样自由控制创建时间。实际使用时，可以把快照理解成“主动保存一个恢复点”，把自动备份理解成“系统提供的备用恢复记录”。
如果您想进一步了解搬瓦工自带备份功能的使用方式，可以阅读 搬瓦工免费自动备份功能详解：如何导入与恢复数据，里面会更具体地介绍自动备份的导入、恢复和实际使用场景。
| 接口名称 | 主要用途 |
|---|---|
snapshot/create |
创建快照 |
snapshot/list |
查看已有快照列表 |
snapshot/delete |
删除指定快照 |
snapshot/restore |
从指定快照恢复 |
backup/list |
查看系统自动备份列表 |
backup/copyToSnapshot |
将自动备份复制为快照，方便手动管理 |
创建快照时，建议给快照加上清晰的描述，例如日期、用途或操作前说明。如果描述中包含空格、中文或特殊符号，建议使用 --data-urlencode 处理参数，避免因为编码问题导致请求异常。
DESC="before_update_$(date +%Y%m%d_%H%M%S)"
curl -s -X POST "https://api.64clouds.com/v1/snapshot/create" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}" \
--data-urlencode "description=${DESC}"
快照通常会有数量限制，所以如果您准备长期做自动快照，最好同时配合 snapshot/list 和 snapshot/delete，定期删除较旧的快照，只保留最近几份。
4. 系统和网络接口：重装系统、PTR、IPv6 和机房迁移
系统和网络管理类接口影响范围更大，例如重装系统、重置 root 密码、设置主机名、设置 PTR、添加 IPv6、迁移机房等。这类接口可以实现很多面板中的高级功能，但也更容易带来风险，尤其是 reinstallOS。
| 接口名称 | 主要用途 |
|---|---|
reinstallOS |
重装操作系统 |
resetRootPassword |
重置 root 密码 |
setHostname |
修改 VPS 主机名 |
setPTR |
设置反向 DNS 记录 |
ipv6/add |
添加 IPv6 地址 |
migrate/getLocations |
查看可迁移的机房列表 |
migrate/start |
开始迁移到目标机房 |
调用这类接口前，一定要确认自己理解它会产生什么后果。尤其是重装系统，通常会清空原系统环境，执行前必须先备份重要文件、数据库和网站配置。
如果您准备用 migrate/getLocations 或 KiwiVM 面板迁移机房，建议先了解目标机房的网络表现、回程路由和流媒体解锁情况。例如 搬瓦工洛杉矶 DC2 QNET 机房：AMD性能/回程路由/流媒体解锁评测 这类评测文章，就适合在迁移前作为参考。
如果您主要关注系统重装，尤其是想通过 KiwiVM 后台安装或升级到 Ubuntu 24.04 LTS，可以参考 搬瓦工 KiwiVM 后台支持一键重装 Ubuntu 24.04 LTS：新特性解析与升级教程，先了解系统模板选择和升级前后的注意事项。
5. Shell 命令接口：通过 API 执行命令的风险说明
KiwiVM API 还提供了通过接口执行 Shell 命令或脚本的能力，例如 basicShell/exec 和 shellScript/exec。这类接口权限非常高，等于允许您通过 API 在 VPS 中执行命令。
| 接口名称 | 主要用途 |
|---|---|
basicShell/exec |
同步执行一条 Shell 命令 |
shellScript/exec |
异步执行 Shell 脚本 |
如果 API KEY 泄露，这两个接口的风险会非常高。别人不仅可能重启您的 VPS，还可能直接执行命令。因此，不建议把 API KEY 放在前端网页、公开脚本、公开 GitHub 仓库或不可信的第三方管理工具里。执行命令类接口时，也应该优先使用 POST，并注意参数转义和编码。
由于这类接口风险较高，本文不提供具体执行命令示例。新手用户建议优先使用 SSH 客户端登录 VPS 后手动执行命令，不要一开始就通过 API 执行 Shell。
六、使用 Python 封装 KiwiVM API 调用脚本
curl 适合快速测试接口，但如果您准备长期使用 KiwiVM API 做自动化，Python 会更适合。因为 Python 更容易处理 JSON、判断错误、设置超时、写日志，也更方便后续接入邮件、Telegram、企业微信等通知方式。
使用 Python 前，可以先安装 requests 库。如果系统同时安装了 Python 2 和 Python 3，建议优先使用 pip3：
pip3 install requests
如果您的系统里只有 pip，也可以使用：
pip install requests
为了避免把 API KEY 直接写死在代码里，建议使用环境变量保存密钥。比如在终端中设置：
export KIWIVM_VEID="YOUR_VEID" export KIWIVM_API_KEY="YOUR_API_KEY"
然后可以写一个基础调用函数：
import os
import requests
BASE_URL = "https://api.64clouds.com/v1"
VEID = os.environ["KIWIVM_VEID"]
API_KEY = os.environ["KIWIVM_API_KEY"]
def call_api(action, params=None):
data = {
"veid": VEID,
"api_key": API_KEY,
}
if params:
data.update(params)
response = requests.post(
f"{BASE_URL}/{action}",
data=data,
timeout=20
)
response.raise_for_status()
result = response.json()
if result.get("error") != 0:
raise RuntimeError(
f"KiwiVM API error {result.get('error')}: {result.get('message')}"
)
return result
if __name__ == "__main__":
info = call_api("getServiceInfo")
print("Hostname:", info.get("hostname"))
print("Status:", info.get("ve_status"))
print("OS:", info.get("os"))
print("IP:", info.get("ip_addresses"))
这个示例比直接拼接 URL 更适合长期使用。它使用 POST 传参，减少 API KEY 出现在 URL 中的机会；它设置了 timeout，避免网络异常时脚本一直卡住；它还检查了 error 字段，如果接口返回错误，会直接抛出异常，方便您在日志中发现问题。
七、KiwiVM API 自动化实战：快照、状态监控和流量提醒
理解了基本调用方式之后，接下来就可以把 KiwiVM API 用到实际场景里。对于大多数用户来说，最实用的不是把所有接口都记下来，而是先解决几个具体问题：如何自动创建快照，如何监控 VPS 是否在线，如何在流量快用完时提醒自己。
如果您的 VPS 上运行的是 Dify、网站程序或其他长期在线服务，自动快照和状态监控会更有意义。比如准备搭建 AI 智能体服务的用户，可以先阅读 搬瓦工 VPS 部署 AI 智能体：Dify 安装教程与配置指南，完成部署后再回到本文配置快照、流量提醒和运行状态监控。
为了避免和前面的安全建议冲突，下面的长期脚本示例默认从环境变量读取 VEID 和 API KEY。如果只是临时在当前终端测试脚本，可以先这样设置：
export KIWIVM_VEID="YOUR_VEID" export KIWIVM_API_KEY="YOUR_API_KEY"
不过需要注意，如果脚本通过 crontab 定时执行，crontab 不一定会读取您当前终端里临时 export 的环境变量。更稳妥的做法是把变量写入一个只有 root 可读的配置文件，然后在脚本开头加载这个文件。
cat > /root/.kiwivm_api <<'EOF' export KIWIVM_VEID="YOUR_VEID" export KIWIVM_API_KEY="YOUR_API_KEY" EOF chmod 600 /root/.kiwivm_api
然后在自动快照脚本或监控脚本开头加入下面这一行：
source /root/.kiwivm_api
这样即使脚本由 crontab 执行，也能正确读取 VEID 和 API KEY。
1. 每天自动创建 VPS 快照
如果您经常修改 VPS 环境，或者 VPS 上运行着比较重要的网站，自动快照会很有用。它不能替代完整备份，但可以在系统配置出错时提供一个快速恢复点。快照更适合用于系统回滚，不能完全替代异地备份。重要网站数据、数据库和配置文件，仍然建议定期备份到其他存储位置。
下面是一个简单的自动快照脚本：
#!/bin/bash
source /root/.kiwivm_api
VEID="${KIWIVM_VEID:?请先设置 KIWIVM_VEID}"
API_KEY="${KIWIVM_API_KEY:?请先设置 KIWIVM_API_KEY}"
DATE=$(date +%Y%m%d_%H%M%S)
DESC="auto_snapshot_${DATE}"
RESULT=$(curl -sS --connect-timeout 10 -m 30 -X POST "https://api.64clouds.com/v1/snapshot/create" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}" \
--data-urlencode "description=${DESC}")
echo "[$(date '+%F %T')] ${RESULT}" >> /var/log/kiwivm_snapshot.log
把脚本保存为：
/root/kiwivm_snapshot.sh
然后赋予执行权限：
chmod +x /root/kiwivm_snapshot.sh
接着编辑 crontab：
crontab -e
添加下面这一行，让脚本每天凌晨 3 点执行一次：
0 3 * * * /root/kiwivm_snapshot.sh
这样设置后，系统会每天自动创建一个带日期时间的快照。需要提醒的是，快照数量通常有限制。如果长期使用这个脚本，建议再写一个快照轮转逻辑，只保留最近几份，避免快照数量用满。
2. 定时监控 VPS 是否正常运行
有些用户希望 VPS 异常停止时能自动尝试启动。这个需求可以通过定时查询 VPS 状态实现。脚本定期调用 getLiveServiceInfo，如果接口正常返回，并且状态不是 running，再调用 start 接口尝试启动 VPS。
下面这个示例比简单读取 ve_status 更稳一些，它会先检查 API 返回的 error 字段。如果接口返回错误、网络请求失败或 JSON 解析失败，脚本会记录日志并退出，避免误判 VPS 状态。
#!/bin/bash
source /root/.kiwivm_api
VEID="${KIWIVM_VEID:?请先设置 KIWIVM_VEID}"
API_KEY="${KIWIVM_API_KEY:?请先设置 KIWIVM_API_KEY}"
LOG_FILE="/var/log/kiwivm_monitor.log"
RESPONSE=$(curl -sS --connect-timeout 10 -m 30 -X POST "https://api.64clouds.com/v1/getLiveServiceInfo" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}")
if [ $? -ne 0 ]; then
echo "[$(date '+%F %T')] API request failed." >> "${LOG_FILE}"
exit 1
fi
ERROR=$(printf '%s' "$RESPONSE" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("error","parse_failed"))' 2>/dev/null)
if [ "$ERROR" != "0" ]; then
echo "[$(date '+%F %T')] API returned error or invalid JSON: ${RESPONSE}" >> "${LOG_FILE}"
exit 1
fi
STATUS=$(printf '%s' "$RESPONSE" | python3 -c 'import sys,json; print(str(json.load(sys.stdin).get("ve_status","unknown")).lower())' 2>/dev/null)
if [ "$STATUS" != "running" ]; then
echo "[$(date '+%F %T')] VPS status is ${STATUS}, trying to start..." >> "${LOG_FILE}"
curl -sS --connect-timeout 10 -m 30 -X POST "https://api.64clouds.com/v1/start" \
-d "veid=${VEID}" \
-d "api_key=${API_KEY}" >> "${LOG_FILE}"
fi
如果您希望每 5 分钟检查一次，可以添加下面的 crontab 任务：
*/5 * * * * /root/kiwivm_monitor.sh
这个脚本仍然只是基础版本，适合入门理解。如果要用于生产环境，建议再加上通知功能，比如 VPS 异常时发送邮件、Telegram 或企业微信提醒。否则脚本虽然尝试启动了 VPS，但您可能并不知道它曾经出现过异常。
3. 监控月流量使用情况并设置提醒
搬瓦工 VPS 通常有月流量限制。如果流量接近用完，可能会影响正常使用。通过 getServiceInfo 接口返回的 plan_monthly_data 和 data_counter 字段，可以计算当前流量使用比例。
下面是一个 Python 示例，当流量使用超过 85% 时输出提醒：
import os
import requests
VEID = os.environ["KIWIVM_VEID"]
API_KEY = os.environ["KIWIVM_API_KEY"]
URL = "https://api.64clouds.com/v1/getServiceInfo"
THRESHOLD = 0.85
response = requests.post(
URL,
data={
"veid": VEID,
"api_key": API_KEY,
},
timeout=20
)
response.raise_for_status()
info = response.json()
if info.get("error") != 0:
raise RuntimeError(info.get("message", "Unknown API error"))
monthly = info.get("plan_monthly_data", 0)
used = info.get("data_counter", 0)
if monthly <= 0:
raise RuntimeError("Invalid monthly traffic value")
usage = used / monthly
print(f"已用流量：{used / 1024 / 1024 / 1024:.2f} GB")
print(f"总流量：{monthly / 1024 / 1024 / 1024:.2f} GB")
print(f"使用比例：{usage:.2%}")
if usage >= THRESHOLD:
print("警告：流量使用已经超过阈值，请注意控制流量。")
这个脚本也需要读取前面保存的环境变量。如果通过 crontab 每天执行一次，可以这样写，例如每天上午 9 点检查：
0 9 * * * /bin/bash -lc 'source /root/.kiwivm_api && /usr/bin/python3 /root/check_traffic.py'
如果后续想进一步完善，可以把最后的 print 提醒改成邮件、Telegram Bot 或其他通知方式。这样当流量接近上限时，您就能及时收到提醒，而不是等到服务受影响后才发现。
八、API KEY 安全注意事项：避免泄露和误用
使用 KiwiVM API 时，最需要重视的不是接口怎么调用，而是 API KEY 怎么保护。因为 API KEY 一旦泄露，别人可能通过接口操作您的 VPS。轻则重启、关机，重则重装系统、执行命令，造成数据丢失或服务中断。
1. 不要把 API KEY 写进公开代码
很多新手为了方便，会直接在脚本里写 API_KEY="private_xxxxx"。如果这个脚本只保存在本地服务器上，风险还算可控；但如果您把它上传到 GitHub、博客附件、公开网盘，就等于把 VPS 管理密钥公开了。更稳妥的做法是使用环境变量、私有配置文件，或者专门的密钥管理工具。
2. 不要把 API KEY 填到不可信的网站或 APP
有些第三方工具可能声称可以帮您管理搬瓦工 VPS，但只要它要求您输入 API KEY，您就要非常谨慎。除非您确认工具可信、开源，并且密钥只保存在本地，否则不建议使用。
3. 优先使用 POST 请求，减少密钥暴露
GET 请求会把 API KEY 放在 URL 里，例如：
?veid=1234567&api_key=private_xxxxx
这种写法虽然简单，但容易出现在浏览器历史、Shell history、代理日志或服务器访问日志中。相比之下，POST 更适合脚本长期使用。
4. 注意参数编码，避免请求异常
如果参数中包含空格、中文、&、?、#、引号或换行，直接拼接 URL 可能导致请求异常。比如快照描述、PTR 记录、Shell 命令和脚本内容，都可能遇到编码问题。如果不确定如何处理，优先使用 POST 传参，不要手动拼接很长的 URL。
5. 怀疑 API KEY 泄露后立即重置
如果您不小心把 API KEY 发给了别人，或者上传到了公开仓库，不要想着“应该没人看到”。正确做法是马上进入 KiwiVM 面板重置 API KEY，并检查 Audit log 中是否有异常操作记录。
九、KiwiVM API 常见问题与排查方法
使用 KiwiVM API 时，最常见的问题一般集中在认证失败、请求超时、被限流、快照创建失败等几个方面。遇到问题时，不要急着怀疑接口不可用，可以先按下面的思路排查。
1. 提示 Authentication failure 怎么办？
这通常表示 VEID 或 API KEY 不正确。您可以先检查 VEID 是否属于当前这台 VPS，API KEY 是否以 private_ 开头，复制时有没有多余空格或换行。如果您最近重置过 API KEY，也要确认脚本里已经换成新的密钥。多台 VPS 用户还要特别注意，不要把 A 机器的 VEID 和 B 机器的 API KEY 混在一起。
2. API 请求没反应或超时怎么办？
这种情况可能是网络问题，也可能是接口本身响应较慢。比如 getLiveServiceInfo 这类实时信息接口，返回速度可能比普通查询接口慢。建议脚本中设置 timeout，例如 Python 中使用 requests.post(url, data=data, timeout=20)，避免程序一直卡住。
3. 调用太频繁被限流怎么办？
API 通常会有限流机制。如果短时间内请求太多，可能会被临时限制。定时监控不需要过于频繁，一般 5 分钟一次已经够用。批量管理多台 VPS 时，也建议每台之间加一点延迟，不要同时大量请求。必要时，可以通过 getRateLimitStatus 接口查看当前限流状态。
4. 创建快照失败怎么办？
快照创建失败可能是快照数量已满，也可能是 VPS 当前状态不适合创建快照，或者请求参数中包含特殊字符但没有正确处理。您可以先调用 snapshot/list 查看当前已有快照数量，如果数量已经满了，就需要删除旧快照后再创建新的快照。
5. 为什么重装系统接口要谨慎使用？
因为重装系统通常会清空原来的系统环境。如果您通过 reinstallOS 接口重装 VPS，却没有提前备份网站文件、数据库和配置文件，可能会造成不可恢复的数据损失。因此，不建议把重装系统接口放进无人值守的自动化脚本里。
如果您的目标不是重装 Linux，而是想在搬瓦工 VPS 上安装 Windows，可以单独查看 搬瓦工安装Windows教程：从零到成功进入桌面（含排错实战）。Windows 安装流程和普通 Linux 模板重装不一样，不建议直接套用本文的 API 示例。
十、总结
KiwiVM API 的核心逻辑并不复杂。准备好 VEID 和 API KEY 后，向指定接口发送请求，就可以查询 VPS 信息或执行对应操作。新手建议先从 getServiceInfo 开始，确认接口可以正常访问后，再逐步尝试快照、监控和流量提醒等自动化场景。
如果您只是偶尔管理一台 VPS，KiwiVM 面板已经足够；如果您希望减少重复操作，或者需要批量管理多台 VPS，KiwiVM API 就很值得学习。使用过程中一定要保护好 API KEY，不要公开、不要乱填、不要上传到公开仓库，怀疑泄露时应第一时间重置。