什么是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/
需要携带veid和api_key参数
get与post请求方法都可以 但get请求有长度限制.如果执行一些长的命令 最终还是需要post请求方法 post也更加安全
https://api.64clouds.com/v1/api的请求路径?veid=YOUR_VEID&api_key=YOUR_API_KEY
使用时需要把文字部分替换为指定的内容
3处要替换的地方
- api的请求路径 也就是你需要执行的功能特点
- YOUR_VEID 你的VPSid
- 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: 是否有需要注意的活动策略违规(参见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: 可用过程系统的数组
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
