搬瓦工api运用 请勿泄漏Key

搬瓦工API通过HTTP请求实现对VPS的自动化控制,支持开机、关机、查询状态及执行命令等操作,核心接口地址为https://api.64clouds.com/v1/,需提供veid和api_key参数。建议使用POST方法发送请求以避免长度限制并提升安全性,可通过curl、wget或Python的requests库调用,成功返回JSON格式数据,认证失败则提示错误码700005。API密钥须严格保密,泄露后应立即重置。

什么是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 不要泄露给任何人 防止VPS和API被盗用 如果发生泄漏请使用Reset API Key重置也应当保护调用API所在的设备

API的使用

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

需要携带veidapi_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 你的VPSid
  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启动 VPSstop停止 VPSrestart重启 VPSkill允许强制停止一个卡死且无法通过正常手段停止的 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: 是否有需要注意的活动策略违规(参见getPolicyViolationssuspension_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: 可用过程系统的数组

reinstallOSos重装流程系统。必须通过os变量指定操作系统。使用getAvailableOS调用获取可用系统列表。Returns (返回值)

rootPassword: 新的 root 密码

sshPort: SSH 端口

sshKeys: 上传到/root/.ssh/authorized_keys的 SSH 密钥

sshKeysBrief: SSH 密钥(视觉展示用的缩短版)

notificationEmail: 完成时发送通知的电子邮件地址

updateSshKeysssh_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(审计日志)”下显示的详细审计日志。setHostnamenewHostname设置新的主机名。setPTRip,ptr为 IP 设置新的 PTR (rDNS) 记录。iso/mountiso设置要引导的 ISO 镜像。在此 API 调用后,VM 必须完全关机并重新启动。iso/unmount移除 ISO 镜像并设置 VM 从主存储引导。在此 API 调用后,VM 必须完全关机并重新启动。basicShell/cdcurrentDir,newDir模拟 VPS 内部的目录更改。可用于构建类似“Basic shell”的 shell。Returns (返回值)pwd: 更改后的 “pwd” 命令结果。

basicShell/execcommand在 VPS 上执行 shell 命令(同步)。Returns (返回值)

error: 已执行命令的退出状态代码

message: 已执行命令的控制台输出

shellScript/execscript在 VPS 上执行 shell 脚本(异步)。Returns (返回值)

log: 输出日志文件的名称。

snapshot/createdescription(可选)创建快照Returns (返回值)

notificationEmail: 任务完成后将发送通知的文件中的电子邮件地址。

snapshot/list获取快照列表。Returns (返回值)

snapshots: 快照数组(fileName, os, description, size, md5, sticky, purgesIn, downloadLink, downloadLinkSSL)。

snapshot/deletesnapshot按文件名删除快照(可通过snapshot/list调用检索)。snapshot/restoresnapshot按文件名还原快照(可通过snapshot/list调用检索)。这将覆盖 VPS 上的所有数据。snapshot/toggleStickysnapshot,sticky设置或移除 sticky 属性(“sticky”快照永远不会被清除)。快照名称可通过snapshot/list调用检索——查找 fileName 变量。设置 sticky = 1 以设置 sticky 属性设置 sticky = 0 以移除 sticky 属性

snapshot/exportsnapshot生成一个令牌 (token),通过该令牌可以将快照传输到另一个实例。snapshot/importsourceVeid,sourceToken从由 VEID 和 Token 标识的另一个实例导入快照。VEID 和 Token 必须事先通过snapshot/export调用从另一个实例获得。backup/list获取自动备份列表。Returns (返回值)

backups: 备份数组(backupToken, size, os, md5, timestamp)。

backup/copyToSnapshotbackupToken将由backupToken(由backup/list返回)标识的备份复制为可还原的快照。ipv6/add分配一个新的 IPv6 /64 子网。Returns (返回值)assigned_subnet: 新分配的 IPv6 /64 子网

ipv6/deleteip释放指定的 IPv6 /64 子网。migrate/getLocations返回所有可能的迁移位置。Returns (返回值)currentLocation: 当前位置的 ID

locations: 可迁移到的位置 ID

descriptions: 可用位置的友好描述

dataTransferMultipliers: 某些位置可能提供更昂贵的带宽,其每月限额将更低。此数组包含每个位置的每月数据传输限额倍率。

migrate/startlocation启动 VPS 迁移到新位置。输入新位置 ID。请注意,这将导致所有 IPv4 地址被替换。Returns (返回值)

notificationEmail: 任务完成后将发送通知的文件中的电子邮件地址。

newIps: 分配给 VPS 的新 IP 地址数组。

cloneFromExternalServerexternalServerIP,externalServerSSHport,externalServerRootPassword(仅限 OVZ) 克隆远程服务器或 VPS。请参阅“从另一台服务器迁移”以了解其工作原理的示例。getSuspensionDetails检索与服务暂停相关的信息。Returns (返回值)suspension_count: 本日历年内服务被暂停的次数

total_abuse_points: 本日历年内累计的滥用积分总数max_abuse_points: 套餐在本日历年内允许的最大滥用积分

suspensions: 所有未解答疑问的数组以及滥用的支持证据。参见下方示例。evidence: 投诉的全文或有关问题的更多详细信息

服务暂停时的示例输出:

[suspensions] => Array

 (

  => 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

 (

  => "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

 (

  => 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

unsuspendrecord_id清除由record_id标识的滥用难题并解封 VPS。详情请参阅getSuspensionDetails调用。resolvePolicyViolationrecord_id将策略违规标记为已解决。这是避免服务暂停所必需的。详情请参阅getPolicyViolations调用。getRateLimitStatus当您在短时间内执行过多的 API 调用时,KiwiVM API 可能会开始在几分钟内丢弃您的请求。此调用允许监控此事。Returns (返回值)

remaining_points_15min: 当前 15 分钟间隔内可应用的“点数”remaining_points_24h: 当前 24 小时间隔内可使用的“点数”

privateIp/getAvailableIps返回所有可用的(空闲)IPv4 地址,您可以在 VM 上激活这些地址Returns (返回值)available_ips: 可用私有 IP 地址的数组。

privateIp/assignip(可选)分配私有 IP 地址。如果未指定 IP 地址,将分配一个随机地址。Returns (返回值)assigned_ips: 成功分配的私有 IP 地址数组

privateIp/deleteip删除私有 IP 地址。kiwivm/getNotificationPreferences返回所有可用的通知设置及其状态Returns (返回值)email_preferences: 可用通知及其状态的数组notificationEmail: 当前部署的发送通知的电子邮件地址

kiwivm/setNotificationPreferencesjson_notification_preferences(json 格式的数组, preference_id:0/1)更改通知首选项Returns (返回值)

submitted_email_preferences: 已提交更改的数组updated_email_preferences: 实际已更改的首选项数组friendly_descriptions: 所有首选项的友好描述

原创文章,作者:banwagong,如若转载,请注明出处:https://bwgcn2gia.com/archives/325.html

(0)
上一篇 01/31/2026 10:12
下一篇 02/01/2026 23:27

相关推荐

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注