使用管理 API：从只读查询开始

1. API 适合做什么，先从只读查询开始#

KiwiVM API 可用于读取实例信息、统计流量和管理实例任务。它管理的是 VPS，不是网站账户的普通登录接口。API 密钥可能拥有停止、重装或恢复磁盘等高权限，不能放进网页前端、公开代码仓库或在线调试网站。

先在服务商账户中进入目标实例的 KiwiVM，再打开 API 菜单。核对实例编号 VEID、密钥显示入口、接口地址和该页当前文档。每台实例的凭据应分开保存，避免把 A 实例的 VEID 与 B 实例的密钥配在一起。

2. 复制接口文档，不复制带密钥的网址#

面板通常列出 getServiceInfo、getLiveServiceInfo 等查询方法，以及启动、停止、快照等写操作。首次只选查询方法，核对当前文档允许的请求方式和参数。

不要把包含 API Key 的 GET 地址收藏到浏览器，URL 可能进入历史记录或代理日志。若文档支持 POST 表单，可把参数放在请求体中；这仍需要 HTTPS，并不意味着可以随意打印请求内容。

3. 用 Python 发起一次受控查询#

把以下代码保存为本机的 query_vps.py。它会交互读取面板给出的只读接口地址、VEID 和密钥，不把密钥写进源文件；先确认接口属于服务商，再输入凭据。示例按常见的 veid、api_key 表单参数和 error 返回字段编写，使用前与自己的 API 页面核对。

import getpass
import json
import urllib.parse
import urllib.request

endpoint = input('粘贴面板中的 HTTPS 只读查询接口：').strip()
url = urllib.parse.urlsplit(endpoint)
if url.scheme != 'https' or url.hostname != 'api.64clouds.com':
    raise SystemExit('请核对服务商接口域名，不向其他地址发送密钥')
if url.path != '/v1/getServiceInfo' or url.query:
    raise SystemExit('本示例只允许 getServiceInfo，且地址不带查询参数')
veid = input('VEID：').strip()
key = getpass.getpass('API Key：')
body = urllib.parse.urlencode({'veid': veid, 'api_key': key}).encode()
request = urllib.request.Request(endpoint, data=body, method='POST')
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)
if result.get('error') != 0:
    raise SystemExit('接口未成功，请核对凭据、权限和面板中的错误说明')
print('查询成功')
for name in ('hostname', 'vm_type', 'plan_ram', 'plan_disk'):
    if name in result:
        print(name, result[name])

不要把完整返回数据公开粘贴；其中可能包含 IP、实例配置和其他运维信息。网络异常应显示失败，不能用上一条成功记录冒充刚刚查询结果。

4. 自动化时保存时间并控制请求频率#

轮询程序应有超时、有限重试和失败退避，遵守面板当前的速率限制。分别保存“最后成功查询时间”和“本次尝试时间”，接口失败时保留旧值并标记时间，避免误导使用者。

流量字段的单位和重置时间格式以文档为准；字节与 GB/GiB 的换算要一致。不要每秒查询所有实例，也不要用重启接口验证密钥是否正确。

5. 导出与撤销密钥#

账户中的“导出全部服务及私有 API Key”文件可能包含所有实例的高权限凭据。只在确有批量管理需求时导出，存放在加密位置，限制文件权限，不能上传到聊天群或普通表格分享链接。

更换密钥后逐个更新任务并做只读验证，再撤销旧密钥。第三方手机管理工具需要输入 API Key 时，先了解其保存和同步方式。重装、停止、恢复快照等操作应有单独确认和审计，不与普通状态查询按钮混在一起。