搬瓦工KiwiVM API接口使用教程

搬瓦工KiwiVM面板提供RESTful API接口，可以通过程序自动化管理VPS，包括查询状态、开关机、重装系统、创建快照等操作。本文介绍API的获取方式、常用接口和Python调用示例。

一、获取API密钥

使用API需要两个参数：VEID（VPS ID）和 API Key。

登录搬瓦工官网 bwh81.net
进入 KiwiVM 面板
在左侧菜单点击 "KiwiVM API"
页面显示 VEID 和 API Key
如果还没有 API Key，点击 "Generate new API key" 生成

Tip： API Key 相当于VPS的管理密码，请妥善保管。不要将API Key存放在公开代码仓库中。

二、API接口基础

API请求格式：

https://api.64clouds.com/v1/{action}?veid={VEID}&api_key={API_KEY}

所有API请求使用 HTTPS GET 方式，返回 JSON 格式数据。

三、常用API接口列表

接口	功能	说明
`getServiceInfo`	获取VPS信息	返回IP、操作系统、内存、硬盘、流量等信息
`getLiveServiceInfo`	获取实时状态	返回实时CPU、内存、硬盘使用率和运行状态
`start`	启动VPS	启动已停止的VPS
`stop`	停止VPS	正常关机停止VPS
`restart`	重启VPS	重启VPS（等同于KiwiVM面板的Reboot）
`kill`	强制停止	强制关机，相当于拔电源
`getAvailableOS`	可用系统列表	返回可安装的操作系统列表
`reinstallOS`	重装系统	需要额外参数 os（系统代号）
`snapshot/create`	创建快照	创建当前系统快照
`snapshot/list`	快照列表	列出所有快照
`snapshot/restore`	恢复快照	需要额外参数 snapshot（快照ID）
`getMigrateLocations`	可迁移机房	返回可迁移的机房列表
`migrate`	迁移机房	需要额外参数 location（机房代号）

四、Python调用示例

1. 获取VPS基本信息

import requests

VEID = "你的VEID"
API_KEY = "你的API_KEY"
BASE_URL = "https://api.64clouds.com/v1"

def get_service_info():
    url = f"{BASE_URL}/getServiceInfo"
    params = {"veid": VEID, "api_key": API_KEY}
    response = requests.get(url, params=params)
    data = response.json()

    print(f"IP地址: {data.get('ip_addresses', ['N/A'])[0]}")
    print(f"操作系统: {data.get('os', 'N/A')}")
    print(f"内存: {data.get('plan_ram', 0) / 1024 / 1024:.0f} MB")
    print(f"硬盘: {data.get('plan_disk', 0) / 1024 / 1024 / 1024:.0f} GB")
    print(f"已用流量: {data.get('data_counter', 0) / 1024 / 1024 / 1024:.2f} GB")
    print(f"总流量: {data.get('plan_monthly_data', 0) / 1024 / 1024 / 1024:.0f} GB")
    return data

get_service_info()

2. 获取实时状态

def get_live_info():
    url = f"{BASE_URL}/getLiveServiceInfo"
    params = {"veid": VEID, "api_key": API_KEY}
    response = requests.get(url, params=params)
    data = response.json()

    status = "运行中" if data.get("ve_status") == "running" else "已停止"
    print(f"状态: {status}")
    print(f"CPU使用: {data.get('ve_proc_quota_used', 'N/A')}")
    print(f"内存使用: {data.get('ve_used_disk_space_b', 0) / 1024 / 1024:.0f} MB")
    return data

get_live_info()

3. VPS控制操作

def control_vps(action):
    """action可以是: start, stop, restart, kill"""
    url = f"{BASE_URL}/{action}"
    params = {"veid": VEID, "api_key": API_KEY}
    response = requests.get(url, params=params)
    data = response.json()

    if data.get("error") == 0:
        print(f"操作成功: {action}")
    else:
        print(f"操作失败: {data.get('message', '未知错误')}")
    return data

# 重启VPS
control_vps("restart")

4. 快照管理

def create_snapshot():
    url = f"{BASE_URL}/snapshot/create"
    params = {"veid": VEID, "api_key": API_KEY}
    response = requests.get(url, params=params)
    return response.json()

def list_snapshots():
    url = f"{BASE_URL}/snapshot/list"
    params = {"veid": VEID, "api_key": API_KEY}
    response = requests.get(url, params=params)
    data = response.json()
    for snap in data.get("snapshots", []):
        print(f"快照: {snap['fileName']} - 大小: {snap['size']} bytes")
    return data

list_snapshots()

五、自动化监控脚本

以下脚本可以定时检查VPS状态，异常时发送通知：

import requests
import time
import smtplib
from email.mime.text import MIMEText

VEID = "你的VEID"
API_KEY = "你的API_KEY"
BASE_URL = "https://api.64clouds.com/v1"
CHECK_INTERVAL = 300  # 每5分钟检查一次

def check_vps_status():
    try:
        url = f"{BASE_URL}/getLiveServiceInfo"
        params = {"veid": VEID, "api_key": API_KEY}
        response = requests.get(url, params=params, timeout=10)
        data = response.json()
        return data.get("ve_status") == "running"
    except Exception as e:
        print(f"检查失败: {e}")
        return False

def send_alert(message):
    """发送邮件告警（需配置SMTP）"""
    print(f"告警: {message}")
    # 此处可接入邮件、Telegram Bot、企业微信等通知渠道

while True:
    if not check_vps_status():
        send_alert("VPS已停止运行，请检查！")
    else:
        print(f"VPS正常运行 - {time.strftime('%Y-%m-%d %H:%M:%S')}")
    time.sleep(CHECK_INTERVAL)

六、API使用注意事项

频率限制：API有请求频率限制，建议两次请求之间至少间隔1秒，监控脚本建议5分钟以上间隔
密钥安全：不要将API Key硬编码在代码中，建议使用环境变量或配置文件
错误处理：每次API调用都应检查返回值中的 error 字段，0表示成功
重装系统：通过API重装系统会立即执行，所有数据将被清除，请谨慎操作
API版本：当前使用的是 v1 版本，搬瓦工可能会更新API版本

Tip： 更多教程请查看新手教程，全部方案请查看搬瓦工方案汇总。