搬瓦工api使用：修订间差异

←上一编辑

可视化wikitext

2026年1月26日 (一) 07:57的最新版本

什么是API

API 的全称是 Application Programming Interface（应用程序编程接口）。通俗地讲就是可以通过直接访问网站地址(url)执行一些功能

API能干嘛

可以在不使用kiwiVM面板里面的按钮或界面执行脚本,发送http请求完成自动开机、关机、查询服务器状态、执行指令等等的目的，这些都是官方提供的功能，适用于自动化程序控制服务器。

如何使用API

使用浏览器或curl或编程语言发送http请求

使用浏览器直接在地址栏输入完整的url 虽然能但一般不使用这种方式

使用curl wget等命令行工具发送http请求

使用php python golang等编程语言发送http请求

使用前准备

获取api key和服务器id(veid)

打开kiwivm面板登陆后打开https://bandwagonhost.com/services 打开你要用api控制的服务器

再次提醒:请务必保管好API Key 不要泄露给任何人防止服务器和API被盗用如果发生泄漏请使用Reset API Key重置也应当保护调用API所在的设备

API的使用

基础的url是:https://api.64clouds.com/v1/

需要携带 veid 和 api_key 参数

get与post请求方法都可以但get请求有长度限制.如果执行一些长的命令最终还是需要post请求方法 post也更加安全

https://api.64clouds.com/v1/api的请求路径?veid=YOUR_VEID&api_key=YOUR_API_KEY

使用时需要把文字部分替换为指定的内容

3处要替换的地方

1. api的请求路径也就是你需要执行的功能

2. YOUR_VEID 你的服务器id

3. YOUR_API_KEY 你的API_Key

以获取服务器信息为例

例如你的 veid=33333 api_key=privateewww324242

需要调用 获取服务器信息 的功能那么请求路径 getServiceInfo

https://api.64clouds.com/v1/getServiceInfo?veid=33333&api_key=privateewww324242

使用时请替换为自己实际的内容使用你选择的工具发送http请求

顺利的话会返回很多数据关键信息已经隐藏…

成功的返回值不同请求路径返回的内容不一样

{
	"vm_type": "kvm",
    "hostname": "xxxx",
    "node_alias": "xxxx",
    "node_location_id": "xxxxx",
    "node_location": "xxxxx",
    "node_datacenter": "xxxxx",
    "location_ipv6_ready": true,
    "plan": "xxxxxx",
    "plan_monthly_data": 0,
    "monthly_data_multiplier": 0,
    "plan_disk": 0,
    "plan_ram": 0,
    "plan_swap": 0,
    "plan_max_ipv6s": 0,
    "os": "xxxx",
    "email": "xxxxxx",
    "data_counter": 0,
    "data_next_reset": 0,
    "ip_addresses": [
        "xxx.xxx.xxx.xx"
    ],
    等一些信息 在此省略
}

失败的返回值这个示范是身份验证错误就是api_key或者veid不正确

{
"error": 700005,
"message": "Authentication failure"
}

其他示例

curl 调用：开启服务器 (start)

#GET 方法
curl "https://api.64clouds.com/v1/start?veid=YOUR_VEID&api_key=YOUR_API_KEY"


#POST方法
curl -X POST "https://api.64clouds.com/v1/start" \
     -d "veid=YOUR_VEID" \
     -d "api_key=YOUR_API_KEY"

wget 调用：关闭服务器 (stop)

wget默认会下载文件，加上-qO-可以让它像 curl 一样直接输出结果到屏幕，而不保存文件。

#GET方法
wget -qO- "https://api.64clouds.com/v1/stop?veid=YOUR_VEID&api_key=YOUR_API_KEY"


#POST方法
wget -qO- --post-data="veid=YOUR_VEID&api_key=YOUR_API_KEY" "https://api.64clouds.com/v1/stop"

Python调用:执行命令在服务器的/tmp目录下创建一个文件(basicShell/exec)

Python 的 requests 库会自动处理 URL 编码，非常方便。

如果没安装的话

pip install requests

#GET
import requests
import json

# 配置信息
url = "https://api.64clouds.com/v1/basicShell/exec"
params = {
    "veid": "YOUR_VEID",
    "api_key": "YOUR_API_KEY",
    "command": "touch /tmp/python_test.txt"  # 创建一个文件
}

# 发送请求
try:
    response = requests.get(url, params=params)
    response.raise_for_status() # 检查 HTTP 错误
    
    result = response.json()
    print(f"执行状态码: {result.get('error')}")
    print(f"返回消息: {result.get('message')}")
    
except Exception as e:
    print(f"请求出错: {e}")
    
#POST
import requests
import json

# 配置信息
url = "https://api.64clouds.com/v1/basicShell/exec"

# 这里的字典数据将作为 POST 的 Body 发送
payload = {
    "veid": "YOUR_VEID",
    "api_key": "YOUR_API_KEY",
    "command": "touch /tmp/python_test_post.txt"  # 我改了下文件名，方便你区分
}

# 发送请求
try:
    response = requests.post(url, data=payload)
    
    response.raise_for_status() # 检查 HTTP 错误
    
    result = response.json()
    print(f"执行状态码: {result.get('error')}")
    print(f"返回消息: {result.get('message')}")
    
except Exception as e:
    print(f"请求出错: {e}")

PHP 示例:执行命令在服务器的/tmp目录下创建一个文件(basicShell/exec)

PHP 自带的http_build_query函数可以完美处理 URL 编码。

#GET
<?php
$url = "https://api.64clouds.com/v1/basicShell/exec";

$data = [
    'veid'    => 'YOUR_VEID',
    'api_key' => 'YOUR_API_KEY',
    'command' => 'touch /tmp/php_test.txt' // 创建一个文件
];

// 构建查询字符串 (会自动进行 URL 编码)
$queryString = http_build_query($data);
$requestUrl = $url . '?' . $queryString;

// 发送请求
$response = file_get_contents($requestUrl);

if ($response !== false) {
    $json = json_decode($response, true);
    echo "Error Code: " . $json['error'] . "\n";
    echo "Message: " . $json['message'] . "\n";
} else {
    echo "请求失败\n";
}
?>

#POST
<?php
$url = "https://api.64clouds.com/v1/basicShell/exec";

// 你的数据 (保持不变)
$data = [
    'veid'    => 'YOUR_VEID',
    'api_key' => 'YOUR_API_KEY',
    'command' => 'touch /tmp/php_post_test.txt' // 改了个文件名方便区分
];

// 1. 依然需要用 http_build_query 处理数据，
// 但这次不是拼在 URL 后面，而是放在 Body 里
$content = http_build_query($data);

// 2. 创建 HTTP 头部选项
$options = [
    'http' => [
        'method'  => 'POST', // 显式指定 POST
        'header'  => 'Content-type: application/x-www-form-urlencoded', // 必须告诉服务器这是表单数据
        'content' => $content // 把数据放入 Body
    ]
];

// 3. 创建流上下文 (Stream Context)
$context  = stream_context_create($options);

// 4. 发送请求
// 注意：这里 URL 还是干净的 URL，把 $context 作为第三个参数传进去
$response = file_get_contents($url, false, $context);

// 5. 处理结果
if ($response !== false) {
    $json = json_decode($response, true);
    // 加上 isset 检查防止报错
    $err = isset($json['error']) ? $json['error'] : 'Unknown';
    $msg = isset($json['message']) ? $json['message'] : 'No message';
    
    echo "Error Code: " . $err . "\n";
    echo "Message: " . $msg . "\n";
} else {
    echo "请求失败\n";
}
?>

Golang 示例:执行命令在服务器的/tmp目录下创建一个文件(basicShell/exec)

Go 语言使用net/url包来构建参数。

#GET
package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	baseURL := "https://api.64clouds.com/v1/basicShell/exec"
	
	// 设置参数
	params := url.Values{}
	params.Add("veid", "YOUR_VEID")
	params.Add("api_key", "YOUR_API_KEY")
	params.Add("command", "touch /tmp/golang_test.txt") // 创建一个文件

	// 拼接 URL (Encode() 会自动处理空格和特殊字符)
	fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())

	// 发送 GET 请求
	resp, err := http.Get(fullURL)
	if err != nil {
		fmt.Printf("请求失败: %s\n", err)
		return
	}
	defer resp.Body.Close()

	// 读取响应
	body, _ := ioutil.ReadAll(resp.Body)

	// 解析 JSON (可选)
	var result map[string]interface{}
	if err := json.Unmarshal(body, &result); err == nil {
		fmt.Printf("Error Code: %v\n", result["error"])
		fmt.Printf("Message: %v\n", result["message"])
	} else {
		fmt.Println(string(body))
	}
}

#POST
package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	// 1. 这里的 URL 不需要拼接参数了，只写接口地址
	baseURL := "https://api.64clouds.com/v1/basicShell/exec"
	
	// 2. 设置参数 (这一步保持不变，还是用 url.Values)
	params := url.Values{}
	params.Set("veid", "YOUR_VEID")      // 习惯上用 Set 替换 Add (防止重复)，效果一样
	params.Set("api_key", "YOUR_API_KEY")
	params.Set("command", "touch /tmp/golang_post_test.txt") // 改个文件名区分

	// 3. 发送 POST 请求 (核心修改)
	// http.PostForm 这个函数专门用于发送 form-data
	// 它会自动设置 Content-Type: application/x-www-form-urlencoded
	// 并且把 params 编码放在 Body 里
	resp, err := http.PostForm(baseURL, params)
	
	if err != nil {
		fmt.Printf("请求失败: %s\n", err)
		return
	}
	defer resp.Body.Close()

	//读取响应
	body, _ := ioutil.ReadAll(resp.Body)

	// 解析 JSON
	var result map[string]interface{}
	if err := json.Unmarshal(body, &result); err == nil {
		fmt.Printf("Error Code: %v\n", result["error"])
		fmt.Printf("Message: %v\n", result["message"])
	} else {
		fmt.Println(string(body))
	}
}

常见错误

这个是说没有发现veid参数有可能没写或者写错了

比如 https://api.64clouds.com/v1/getServiceInfo?这里缺少了veid&api_key=privateewww324242

这个自然就是缺少api_key啦

比如 https://api.64clouds.com/v1/getServiceInfo?veid=3232&这里缺少了api_key

API:invalidrequest 未验证的请求

请求路径错误…就是说https://api.64clouds.com/v1/stare?veid=33333&api_key=privateewww324242 把start错误拼写成了stare

身份验证失败

veid或api_key错误

请注意

当您的参数中含有特殊字符例如调用basicShell/exec 接口执行ls -la /var/log指令时 https://api.64clouds.com/v1/basicShell/exec?veid=33333&api_key=privateewww324242&command=ls -la /var/log 您需要使用url编码变为&command=ls%20-la%20%2Fvar%2Flog 具体怎样url编码和您使用的工具有关
请妥善使用API 避免滥用等问题
当您在短时间内执行过多的 API 调用时，KiwiVM API 可能会开始在几分钟内丢弃您的请求。此调用允许监控此事。详情请查看请求路径 getRateLimitStatus 的描述和返回值列

官方API文档的翻译

更新时间utc 2026/01/20 05:58


请求路径	参数	描述和返回值
start		启动 VPS
stop		停止 VPS
restart		重启 VPS
kill		允许强制停止一个卡死且无法通过正常手段停止的 VPS。请务必谨慎使用此功能，因为任何未保存的数据都将丢失
getServiceInfo		获取服务信息 Returns (返回值)： vm_type: 虚拟化类型（ovz 或 kvm） hostname: VPS 的主机名 node_alias: 物理节点的内部昵称 node_location: 物理位置（国家，州/省） location_ipv6_ready: 当前位置是否支持 IPv6 plan: 套餐名称 plan_disk: 磁盘配额（字节） plan_ram: 内存（字节） plan_swap: SWAP 交换分区（字节） os: 操作系统 email: 账户的主电子邮件地址 plan_monthly_data: 每月允许的数据传输量（字节）。需要乘以 `monthly_data_multiplier`（见下文）。 data_counter: 当前计费月份已使用的数据传输量。需要乘以 `monthly_data_multiplier`（见下文）。 monthly_data_multiplier: 某些位置提供更昂贵的带宽；此变量包含带宽核算系数。 data_next_reset: 传输计数器重置的日期和时间（UNIX 时间戳） ip_addresses: 分配给 VPS 的 IPv4 地址和 IPv6 /64 子网（数组）private_ip_addresses: 分配给 VPS 的私有 IPv4 地址（数组） ip_nullroutes: 关于 (D)DoS 攻击期间 IP 地址空路由封禁的信息（数组）。 iso1: 已挂载的镜像 #1 iso2: 已挂载的镜像 #2（目前不支持） available_isos: 可供使用的 ISO 镜像数组 plan_max_ipv6s: 套餐允许的最大 IPv6 /64 子网数量 rdns_api_available: 是否可以通过 API 设置 rDNS 记录plan_private_network_available: 此套餐是否可以使用私有网络功能location_private_network_available: 此位置是否可以使用私有网络功能 ptr: rDNS 记录（二维数组：ip=>value） suspended: VPS 是否被暂停 policy_violation: 是否有需要注意的活动策略违规（参见 `getPolicyViolations`）suspension_count: 本日历年内服务被暂停的次数 total_abuse_points: 本日历年内累计的滥用积分总数 max_abuse_points: 套餐在本日历年内允许的最大滥用积分 [ip_nullroutes] => Array ( [1.2.3.4] => Array ( [nullroute_timestamp] => 1556678627 // start of attack [nullroute_duration_s] => 360 // duration of nullroute [log] => "Packet dump data of the attack (multi-line)" // raw log of attack ) )
getLiveServiceInfo		此函数返回 `getServiceInfo` 提供的所有数据。此外，它还提供 VPS 的详细状态。请注意，此调用可能需要长达 15 秒才能完成。根据虚拟化程序的不同，此调用将返回以下信息： Returns [OVZ hypervisor] (OVZ 虚拟化返回值)： vz_status: 包含 OpenVZ beancounters、系统平均负载、进程数、打开的文件、套接字、内存使用情况等的数组 vz_quota: 包含 OpenVZ 磁盘大小、inode 和使用情况信息的数组 is_cpu_throttled: 0 = CPU 未被限制，1 = 由于高使用率 CPU 被限制。限制每 2 小时自动重置一次。 ssh_port: VPS 的 SSH 端口 Returns [KVM hypervisor] (KVM 虚拟化返回值)： ve_status: Starting（启动中）、Running（运行中）或 Stopped（已停止）ve_mac1: 主网络接口的 MAC 地址 ve_used_disk_space_b: 已占用（映射）的磁盘空间（字节） ve_disk_quota_gb: 磁盘镜像的实际大小（GB） is_cpu_throttled: 0 = CPU 未被限制，1 = 由于高使用率 CPU 被限制。限制每 2 小时自动重置一次。 is_disk_throttled: 0 = 磁盘 I/O 未被限制，1 = 由于高使用率磁盘 I/O 被限制。限制根据持续存储 I/O 利用率每 15-180 分钟自动重置一次。 ssh_port: VPS 的 SSH 端口（仅当 VPS 运行时返回） live_hostname: 在 VPS 内部执行 "hostname" 命令的结果 load_average: 原始平均负载字符串 mem_available_kb: 可用内存量（KB） swap_total_kb: Swap 总量（KB） swap_available_kb: 可用 Swap 量（KB） screendump_png_base64: VGA 控制台的 base64 编码 png 截图
getAvailableOS		获取可用操作系统 Returns (返回值)： installed: 当前安装的操作系统 templates: 可用操作系统的数组
reinstallOS	os	重装操作系统。必须通过 `os` 变量指定操作系统。使用 `getAvailableOS` 调用获取可用系统列表。 Returns (返回值)： rootPassword: 新的 root 密码 sshPort: SSH 端口 sshKeys: 上传到 `/root/.ssh/authorized_keys` 的 SSH 密钥 sshKeysBrief: SSH 密钥（视觉展示用的缩短版） notificationEmail: 完成时发送通知的电子邮件地址
updateSshKeys	ssh_keys	更新 Hypervisor 保管库中的每 VM SSH 密钥。这些密钥将在 `reinstallOS` 调用期间写入 `/root/.ssh/authorized_keys`。这些密钥将覆盖计费门户中设置的任何密钥。
getSshKeys		获取存储在 Hypervisor 保管库以及计费门户中的 SSH 密钥。 Returns (返回值)： ssh_keys_veid: 存储在 Hypervisor 保管库中的每 VM SSH 密钥 ssh_keys_user: 存储在计费门户中的每账户 SSH 密钥 ssh_keys_preferred: 在 `reinstallOS` 调用期间实际使用的 SSH 密钥（每 VM 密钥将始终覆盖每账户密钥） shortened_ssh_keys_veid: 视觉缩短后的密钥 shortened_ssh_keys_user: 视觉缩短后的密钥 shortened_ssh_keys_preferred: 视觉缩短后的密钥
resetRootPassword		生成并设置一个新的 root 密码。 Returns (返回值)： password: 新的 root 密码
getUsageGraphs		已废弃，请改用 `getRawUsageStats`。
getRawUsageStats		返回一个二维数组，包含 KiwiVM 中“Detailed Statistics（详细统计）”下显示的详细使用统计数据。
getAuditLog		返回一个数组，包含 KiwiVM 中“Audit Log（审计日志）”下显示的详细审计日志。
setHostname	newHostname	设置新的主机名。
setPTR	`ip`, `ptr`	为 IP 设置新的 PTR (rDNS) 记录。
iso/mount	iso	设置要引导的 ISO 镜像。在此 API 调用后，VM 必须完全关机并重新启动。
iso/unmount		移除 ISO 镜像并配置 VM 从主存储引导。在此 API 调用后，VM 必须完全关机并重新启动。
basicShell/cd	`currentDir`, `newDir`	模拟 VPS 内部的目录更改。可用于构建类似“Basic shell”的 shell。 Returns (返回值)： pwd: 更改后的 "pwd" 命令结果。
basicShell/exec	command	在 VPS 上执行 shell 命令（同步）。 Returns (返回值)： error: 已执行命令的退出状态代码 message: 已执行命令的控制台输出
shellScript/exec	script	在 VPS 上执行 shell 脚本（异步）。 Returns (返回值)： log: 输出日志文件的名称。
snapshot/create	`description` (可选)	创建快照 Returns (返回值)： notificationEmail: 任务完成后将发送通知的文件中的电子邮件地址。
snapshot/list		获取快照列表。 Returns (返回值)： snapshots: 快照数组（fileName, os, description, size, md5, sticky, purgesIn, downloadLink, downloadLinkSSL）。
snapshot/delete	snapshot	按文件名删除快照（可通过 `snapshot/list` 调用检索）。
snapshot/restore	snapshot	按文件名还原快照（可通过 `snapshot/list` 调用检索）。这将覆盖 VPS 上的所有数据。
snapshot/toggleSticky	`snapshot`, `sticky`	设置或移除 sticky 属性（“sticky”快照永远不会被清除）。快照名称可通过 `snapshot/list` 调用检索——查找 fileName 变量。设置 sticky = 1 以设置 sticky 属性设置 sticky = 0 以移除 sticky 属性
snapshot/export	snapshot	生成一个令牌 (token)，通过该令牌可以将快照传输到另一个实例。
snapshot/import	`sourceVeid`, `sourceToken`	从由 VEID 和 Token 标识的另一个实例导入快照。VEID 和 Token 必须事先通过 `snapshot/export` 调用从另一个实例获得。
backup/list		获取自动备份列表。 Returns (返回值)： backups: 备份数组（backupToken, size, os, md5, timestamp）。
backup/copyToSnapshot	backupToken	将由 `backupToken`（由 `backup/list` 返回）标识的备份复制为可还原的快照。
ipv6/add		分配一个新的 IPv6 /64 子网。 Returns (返回值)：assigned_subnet: 新分配的 IPv6 /64 子网
ipv6/delete	ip	释放指定的 IPv6 /64 子网。
migrate/getLocations		返回所有可能的迁移位置。 Returns (返回值)：currentLocation: 当前位置的 ID locations: 可迁移到的位置 ID descriptions: 可用位置的友好描述 dataTransferMultipliers: 某些位置可能提供更昂贵的带宽，其每月限额将更低。此数组包含每个位置的每月数据传输限额倍率。
migrate/start	location	启动 VPS 迁移到新位置。输入新位置 ID。请注意，这将导致所有 IPv4 地址被替换。 Returns (返回值)： notificationEmail: 任务完成后将发送通知的文件中的电子邮件地址。 newIps: 分配给 VPS 的新 IP 地址数组。
cloneFromExternalServer	`externalServerIP`, `externalServerSSHport`, `externalServerRootPassword`	(仅限 OVZ) 克隆远程服务器或 VPS。请参阅“从另一台服务器迁移”以了解其工作原理的示例。
getSuspensionDetails		检索与服务暂停相关的信息。 Returns (返回值)：suspension_count: 本日历年内服务被暂停的次数 total_abuse_points: 本日历年内累计的滥用积分总数max_abuse_points: 套餐在本日历年内允许的最大滥用积分 suspensions: 所有未解决问题的数组以及滥用的支持证据。参见下方示例。 evidence: 投诉的全文或有关问题的更多详细信息服务暂停时的示例输出: [suspensions] => Array ( [0] => stdClass Object ( [record_id] => 11851 // Case ID, needed to unsuspend // the service via "unsuspend" API call [flag] => copyright // Type of abuse [is_soft] => 1 // 0 = must contact support to unsuspend // 1 = can unsuspend via API call [evidence_record_id] => 2207 // Detailed abuse report ID (see below) [abuse_points] => 100 // Each abuse incident increases total_abuse_points counter ) ) [evidence] => stdClass Object ( [2207] => "Full text of abuse complaint here" ) [suspension_count] => 2 [total_abuse_points] => 200 [max_abuse_points] => 1500
getPolicyViolations		检索与活动策略违规相关的信息。 Returns (返回值)：total_abuse_points: 本日历年内累计的滥用积分总数 max_abuse_points: 套餐在本日历年内允许的最大滥用积分policy_violations: 所有未解决问题的数组以及滥用的支持证据。参见下方示例。当存在活跃的策略违规时，示例输出如下 [policy_violations] => Array ( [0] => Array ( [record_id] => 14 // Case ID, for resolvePolicyViolation [timestamp] => 1571469818 // Unix timestamp when record was created [suspend_at] => 1571599418 // Service will be suspended if not resolved by this time [flag] => copyright // Type of abuse [is_soft] => 1 // 0 = must contact support to unsuspend // 1 = can unsuspend via API call [abuse_points] => 100 // Each abuse incident increases total_abuse_points counter [evidence_data] => // Details of violation (text) ) ) [total_abuse_points] => 200 [max_abuse_points] => 1500 [error] => 0
unsuspend	record_id	清除由 `record_id` 标识的滥用问题并解封 VPS。详情请参阅 `getSuspensionDetails` 调用。
resolvePolicyViolation	record_id	将策略违规标记为已解决。这是避免服务暂停所必需的。详情请参阅 `getPolicyViolations` 调用。
getRateLimitStatus		当您在短时间内执行过多的 API 调用时，KiwiVM API 可能会开始在几分钟内丢弃您的请求。此调用允许监控此事。 Returns (返回值)： remaining_points_15min: 当前 15 分钟间隔内可使用的“点数”remaining_points_24h: 当前 24 小时间隔内可使用的“点数”
privateIp/getAvailableIps		返回所有可用的（空闲）IPv4 地址，您可以在 VM 上激活这些地址 Returns (返回值)： available_ips: 可用私有 IP 地址的数组。
privateIp/assign	`ip` (可选)	分配私有 IP 地址。如果未指定 IP 地址，将分配一个随机地址。 Returns (返回值)： assigned_ips: 成功分配的私有 IP 地址数组
privateIp/delete	ip	删除私有 IP 地址。
kiwivm/getNotificationPreferences		返回所有可用的通知设置及其状态 Returns (返回值)：email_preferences: 可用通知及其状态的数组 notificationEmail: 当前配置的发送通知的电子邮件地址
kiwivm/setNotificationPreferences	`json_notification_preferences` (json 格式的数组, preference_id:0/1)	更改通知首选项 Returns (返回值)： submitted_email_preferences: 已提交更改的数组updated_email_preferences: 实际已更改的首选项数组friendly_descriptions: 所有首选项的友好描述