调用
请求体和响应都是 JSON,只有二维码是 SVG 或 PNG。地址中的名称按 encodeURIComponent 编码,也可以用客户 id 代替名称。点击某个调用,即可看到参数、请求体、响应和现成的命令。地址和令牌可以放在变量里:
VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…令牌、架构、MCP3
GET/me当前令牌:名称、权限、有效期、API 版本任意
application/json{
"name": "cabinet",
"token": true,
"rights": "clients",
"until": 0,
"api": 1
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/me" \
-H "Authorization: Bearer $VELI_TOKEN"GET/openapi.json整个 API 的架构,OpenAPI 3.1只读
application/json{
"openapi": "3.1.0",
"info": { "title": "Veli panel API", "version": "1.12.0" },
"paths": {
"/clients": {
"get": {},
"post": {}
},
"…": {}
}
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/openapi.json" \
-H "Authorization: Bearer $VELI_TOKEN"POST/mcp通过 MCP 供 AI 助手使用的面板任意
application/json{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "clients_list",
"arguments": { "status": "soon" }
}
}application/json{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{ "type": "text", "text": "{\"clients\": [ … ], \"total\": 6}" }
]
}
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/mcp" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"clients_list","arguments":{"status":"soon"}}}'客户12
GET/clients客户:过滤、排序、分页只读
参数
external查询中- 外部 ID——只返回带有它的客户;地址中的“:”写作 %3A
tag查询中- 标签——只返回带有它的客户
status查询中- 状态,用逗号分隔:on、soon、limit、off、paused、waiting
group查询中- 分组;空值——无分组的客户
q查询中- 名称、备注、联系方式或外部 ID 中的词,不区分大小写
until_before查询中- 期限结束早于此时间,unix 时间;永久的不计入
until_after查询中- 期限结束晚于此时间,unix 时间;永久的不计入
changed_since查询中- 自此时间起被手动或系统更改——用于与您自己的数据库核对
devices查询中- none——没有设备,some——有设备,full——名额全部占满
used_over查询中- 已用量不少于限额的这一比例,%;不限流量的客户不计入
seen_before查询中- 应用自此时间起没有获取过订阅——或从未获取过
sort查询中- name、until、added、used 或 changed;前面加“-”——倒序
limit查询中- 每页客户数,1–1000;不填——一次返回全部
cursor查询中- 上一页的 next
application/json{
"at": 1793754000,
"clients": [
{
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null }
}
],
"total": 412,
"next": "eyJrIjoxNzk0MDAwMDAwfQ"
}客户的字段
id- c_ 加 12 个字符——永久不变:重命名不会改变它。可在路径中代替名称:clients/c_Ab3dE5fG7hJ9。在您那边请保存它,而不是名称
name- 名称,1–40 个字符,每位客户各不相同;不能是 c_ 加 12 个字符的形式——id 就长这样
external- 外部 ID——您那边的客户 ID;为空表示没有。它不唯一:一个人可能买两份订阅,所以搜索返回的是列表
tags- 标签
status- on、soon、limit、off、paused 或 waiting——见上文
until- 期限结束时间,unix 时间;0——永久,或期限仍在等待首次连接
wait, first- 期限中有多少秒从首次连接起算(0——不等待);应用首次获取订阅的时间(0——尚未获取)
left- 剩余量:days 和 bytes;null——不限期限、不限流量
devices, held, veli- 允许的设备数、所有应用已占用数、其中 Veli 设备数
speed- Veli 每个方向的速度,Mbit/s;0 为不限
limit, reset, used, next- 流量限额(字节,0 为不限)、重置周期(never、day、week 或 month,按 UTC)、本周期已用量、下一周期开始时间
group- 分组;为空表示无分组
bytes- 累计总流量
seen, changed- 应用最近一次请求订阅的时间(精确到 10 分钟,0——没有);最近一次更改(手动或系统)
note, contact, added- 备注、联系方式、添加时间
错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients?status=on,soon&sort=-until&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/find按链接或设备查找客户;只读令牌在回答中看不到链接只读
application/json{ "link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb" }application/json{
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}客户的字段
id- c_ 加 12 个字符——永久不变:重命名不会改变它。可在路径中代替名称:clients/c_Ab3dE5fG7hJ9。在您那边请保存它,而不是名称
name- 名称,1–40 个字符,每位客户各不相同;不能是 c_ 加 12 个字符的形式——id 就长这样
external- 外部 ID——您那边的客户 ID;为空表示没有。它不唯一:一个人可能买两份订阅,所以搜索返回的是列表
tags- 标签
status- on、soon、limit、off、paused 或 waiting——见上文
until- 期限结束时间,unix 时间;0——永久,或期限仍在等待首次连接
wait, first- 期限中有多少秒从首次连接起算(0——不等待);应用首次获取订阅的时间(0——尚未获取)
left- 剩余量:days 和 bytes;null——不限期限、不限流量
devices, held, veli- 允许的设备数、所有应用已占用数、其中 Veli 设备数
speed- Veli 每个方向的速度,Mbit/s;0 为不限
limit, reset, used, next- 流量限额(字节,0 为不限)、重置周期(never、day、week 或 month,按 UTC)、本周期已用量、下一周期开始时间
group- 分组;为空表示无分组
bytes- 累计总流量
seen, changed- 应用最近一次请求订阅的时间(精确到 10 分钟,0——没有);最近一次更改(手动或系统)
note, contact, added- 备注、联系方式、添加时间
at- 响应生成的时间,unix 时间
link- 订阅链接——是机密:只交给客户本人
page- 供浏览器打开的订阅页面,带应用按钮
apps- 各应用的“添加到 …”链接
list- 设备:id,kind——veli(Veli 密钥)或 app(其他应用的 HWID),os,added;Veli 设备还有 bytes
lines- 各节点的普通协议链接:node、kind、line
meta- 您系统的字段
disabled- true——客户已停用
错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"link":"https://panel.example.com/s/kV0pX7wQ2mLr9sTb"}'POST/clients添加客户客户
application/json{
"name": "order-88123",
"days": 30,
"change": {
"devices": 3,
"external": "88123",
"tags": ["paid", "month"],
"meta": { "order": "88123", "source": "shop" }
}
}change 的字段——每个都可选
days- 续期多少天:从期限结束时算起,已过期的从现在算起;小于零——缩短。对于等待首次连接的客户——延长或缩短等待期。新客户的天数写在 change 旁边,null 为永久。±1–36500
until- 精确的期限结束时间,unix 时间;0——永久。不能与 days 同时使用。设为过去的时间——期限立即结束
start- first_use——期限从应用首次请求订阅时开始;now——等待中的客户立即开始计期
name- 新名称——只能给一个客户;id、链接、设备和流量保持不变
disabled- true——停用:链接打不开,设备从节点上移除,期限照常计算;false——启用
relink- true——更换链接:旧链接失效,普通协议的账号换新,Veli 设备保留
devices- 允许的设备数,1–100
speed- Mbit/s,0–100000;0 为不限
limit, reset, zero- 流量限额(字节)、重置周期,true——从零开始计算
group- 分组名称;为空表示无分组
external- 外部 ID,最多 128 个字符;为空则删除
tags- 标签——整个列表重写:最多 20 个,每个最多 32 个字符
tags_add, tags_remove- 添加和移除标签,其余保留——批量修改时很方便
meta- 您系统的字段——全部重写:最多 20 个;键为拉丁字母、数字和 _ . -,最多 40 个字符;值最多 500 个字符
note, contact- 备注最多 300 个字符,联系方式最多 100 个
过长的值不会被截断,而是返回带字段和上限的 bad 错误——{"error": "bad", "field": "change.devices", "max": 100}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。
application/json{
"done": 1,
"client": {
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}
}客户的字段
id- c_ 加 12 个字符——永久不变:重命名不会改变它。可在路径中代替名称:clients/c_Ab3dE5fG7hJ9。在您那边请保存它,而不是名称
name- 名称,1–40 个字符,每位客户各不相同;不能是 c_ 加 12 个字符的形式——id 就长这样
external- 外部 ID——您那边的客户 ID;为空表示没有。它不唯一:一个人可能买两份订阅,所以搜索返回的是列表
tags- 标签
status- on、soon、limit、off、paused 或 waiting——见上文
until- 期限结束时间,unix 时间;0——永久,或期限仍在等待首次连接
wait, first- 期限中有多少秒从首次连接起算(0——不等待);应用首次获取订阅的时间(0——尚未获取)
left- 剩余量:days 和 bytes;null——不限期限、不限流量
devices, held, veli- 允许的设备数、所有应用已占用数、其中 Veli 设备数
speed- Veli 每个方向的速度,Mbit/s;0 为不限
limit, reset, used, next- 流量限额(字节,0 为不限)、重置周期(never、day、week 或 month,按 UTC)、本周期已用量、下一周期开始时间
group- 分组;为空表示无分组
bytes- 累计总流量
seen, changed- 应用最近一次请求订阅的时间(精确到 10 分钟,0——没有);最近一次更改(手动或系统)
note, contact, added- 备注、联系方式、添加时间
at- 响应生成的时间,unix 时间
link- 订阅链接——是机密:只交给客户本人
page- 供浏览器打开的订阅页面,带应用按钮
apps- 各应用的“添加到 …”链接
list- 设备:id,kind——veli(Veli 密钥)或 app(其他应用的 HWID),os,added;Veli 设备还有 bytes
lines- 各节点的普通协议链接:node、kind、line
meta- 您系统的字段
disabled- true——客户已停用
错误
400 name- 名称为空、超过 40 个字符、含控制字符,是 c_ 加 12 个字符的形式,或是 API 的词:bulk、find
400 taken- 该名称已被占用
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
409 idempotency- 这个 Idempotency-Key 已经用于另一个请求。一个键只对应一个操作:续期和创建用不同的键
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"name":"order-88123","days":30,"change":{"devices":3,"external":"88123","tags":["paid","month"],"meta":{"order":"88123","source":"shop"}}}'GET/clients/{name}完整的客户:链接、应用按钮、设备、字段。只读令牌看不到链接和按钮只读
参数
name路径中- 客户名称或其 id
application/json{
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}客户的字段
id- c_ 加 12 个字符——永久不变:重命名不会改变它。可在路径中代替名称:clients/c_Ab3dE5fG7hJ9。在您那边请保存它,而不是名称
name- 名称,1–40 个字符,每位客户各不相同;不能是 c_ 加 12 个字符的形式——id 就长这样
external- 外部 ID——您那边的客户 ID;为空表示没有。它不唯一:一个人可能买两份订阅,所以搜索返回的是列表
tags- 标签
status- on、soon、limit、off、paused 或 waiting——见上文
until- 期限结束时间,unix 时间;0——永久,或期限仍在等待首次连接
wait, first- 期限中有多少秒从首次连接起算(0——不等待);应用首次获取订阅的时间(0——尚未获取)
left- 剩余量:days 和 bytes;null——不限期限、不限流量
devices, held, veli- 允许的设备数、所有应用已占用数、其中 Veli 设备数
speed- Veli 每个方向的速度,Mbit/s;0 为不限
limit, reset, used, next- 流量限额(字节,0 为不限)、重置周期(never、day、week 或 month,按 UTC)、本周期已用量、下一周期开始时间
group- 分组;为空表示无分组
bytes- 累计总流量
seen, changed- 应用最近一次请求订阅的时间(精确到 10 分钟,0——没有);最近一次更改(手动或系统)
note, contact, added- 备注、联系方式、添加时间
at- 响应生成的时间,unix 时间
link- 订阅链接——是机密:只交给客户本人
page- 供浏览器打开的订阅页面,带应用按钮
apps- 各应用的“添加到 …”链接
list- 设备:id,kind——veli(Veli 密钥)或 app(其他应用的 HWID),os,added;Veli 设备还有 bytes
lines- 各节点的普通协议链接:node、kind、line
meta- 您系统的字段
disabled- true——客户已停用
错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/{name}修改:续期、停用、重命名、更换链接、限额、字段客户
参数
name路径中- 客户名称或其 id
application/json{
"change": {
"days": 30,
"devices": 5,
"tags_add": ["vip"]
}
}change 的字段——每个都可选
days- 续期多少天:从期限结束时算起,已过期的从现在算起;小于零——缩短。对于等待首次连接的客户——延长或缩短等待期。新客户的天数写在 change 旁边,null 为永久。±1–36500
until- 精确的期限结束时间,unix 时间;0——永久。不能与 days 同时使用。设为过去的时间——期限立即结束
start- first_use——期限从应用首次请求订阅时开始;now——等待中的客户立即开始计期
name- 新名称——只能给一个客户;id、链接、设备和流量保持不变
disabled- true——停用:链接打不开,设备从节点上移除,期限照常计算;false——启用
relink- true——更换链接:旧链接失效,普通协议的账号换新,Veli 设备保留
devices- 允许的设备数,1–100
speed- Mbit/s,0–100000;0 为不限
limit, reset, zero- 流量限额(字节)、重置周期,true——从零开始计算
group- 分组名称;为空表示无分组
external- 外部 ID,最多 128 个字符;为空则删除
tags- 标签——整个列表重写:最多 20 个,每个最多 32 个字符
tags_add, tags_remove- 添加和移除标签,其余保留——批量修改时很方便
meta- 您系统的字段——全部重写:最多 20 个;键为拉丁字母、数字和 _ . -,最多 40 个字符;值最多 500 个字符
note, contact- 备注最多 300 个字符,联系方式最多 100 个
过长的值不会被截断,而是返回带字段和上限的 bad 错误——{"error": "bad", "field": "change.devices", "max": 100}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。
application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
400 taken- 该名称已被占用
409 idempotency- 这个 Idempotency-Key 已经用于另一个请求。一个键只对应一个操作:续期和创建用不同的键
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"change":{"days":30,"devices":5,"tags_add":["vip"]}}'GET/clients/{name}/qr链接的二维码:SVG 或 PNG客户
参数
name路径中- 客户名称或其 id
format查询中- svg 或 png;不填为 svg
size查询中- PNG 的边长(像素),128–2048;不填为 512
of查询中- veli——生成“添加到 Veli”链接的二维码,而不是订阅链接
image/svg+xml<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 41 41" shape-rendering="crispEdges">
<path fill="#fff" d="M0 0h41v41H0z"/>
<path d="M4 4h7v1H4z…"/>
</svg>错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123/qr?format=svg" \
-H "Authorization: Bearer $VELI_TOKEN" -o qr.svgGET/clients/{name}/stats客户的每日流量只读
日期按 UTC,从最早到今天;字节为双向合计。
参数
name路径中- 客户名称或其 id
days查询中- 多少天:7、30 或 90;不填为 30
application/json{
"days": ["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"],
"bytes": [0, 52428800, 104857600, 314572800, 209715200, 419430400, 188743680]
}错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"GET/clients/{name}/history客户的历史只读
参数
name路径中- 客户名称或其 id
application/json{
"at": 1793754000,
"client": "order-88123",
"history": [
{
"at": 1793751000,
"kind": "event",
"event": "device.added",
"os": "iOS",
"app": "Happ"
},
{
"at": 1793750460,
"kind": "admin",
"what": "client order-88123",
"by": "cabinet",
"token": true,
"fields": ["days"]
},
{
"at": 1793750400,
"kind": "admin",
"what": "clients add",
"by": "cabinet",
"token": true
}
]
}错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123/history" \
-H "Authorization: Bearer $VELI_TOKEN"GET/clients/{name}/diagnosis客户为什么可能连不上只读
参数
name路径中- 客户名称或其 id
application/json{
"at": 1793754000,
"ok": false,
"checks": [
{ "code": "devices_full", "level": "warn", "action": "unbind", "n": 3 },
{ "code": "nodes_some_down", "level": "info", "n": 1 }
],
"last": { "at": 1793753700, "app": "Happ", "code": 403 }
}错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123/diagnosis" \
-H "Authorization: Bearer $VELI_TOKEN"POST/clients/{name}/unbind解绑设备客户
device——客户 list 中的 id。名额立即释放,可以连接另一台设备。
参数
name路径中- 客户名称或其 id
application/json{ "device": "a1b2c3d4e5f6" }application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123/unbind" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"device":"a1b2c3d4e5f6"}'POST/clients/bulk一次修改多个——要么全部,要么一个不改客户
application/json{
"filter": {
"status": ["on", "soon"],
"tag": "paid"
},
"change": { "days": 3 },
"dry": true
}change 的字段——每个都可选
days- 续期多少天:从期限结束时算起,已过期的从现在算起;小于零——缩短。对于等待首次连接的客户——延长或缩短等待期。新客户的天数写在 change 旁边,null 为永久。±1–36500
until- 精确的期限结束时间,unix 时间;0——永久。不能与 days 同时使用。设为过去的时间——期限立即结束
start- first_use——期限从应用首次请求订阅时开始;now——等待中的客户立即开始计期
name- 新名称——只能给一个客户;id、链接、设备和流量保持不变
disabled- true——停用:链接打不开,设备从节点上移除,期限照常计算;false——启用
relink- true——更换链接:旧链接失效,普通协议的账号换新,Veli 设备保留
devices- 允许的设备数,1–100
speed- Mbit/s,0–100000;0 为不限
limit, reset, zero- 流量限额(字节)、重置周期,true——从零开始计算
group- 分组名称;为空表示无分组
external- 外部 ID,最多 128 个字符;为空则删除
tags- 标签——整个列表重写:最多 20 个,每个最多 32 个字符
tags_add, tags_remove- 添加和移除标签,其余保留——批量修改时很方便
meta- 您系统的字段——全部重写:最多 20 个;键为拉丁字母、数字和 _ . -,最多 40 个字符;值最多 500 个字符
note, contact- 备注最多 300 个字符,联系方式最多 100 个
过长的值不会被截断,而是返回带字段和上限的 bad 错误——{"error": "bad", "field": "change.devices", "max": 100}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。
application/json{
"done": 0,
"matched": 412,
"names": ["order-88123", "order-88124", "…"]
}错误
400 none- 没有这个名称的客户、节点或分组
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
409 idempotency- 这个 Idempotency-Key 已经用于另一个请求。一个键只对应一个操作:续期和创建用不同的键
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/bulk" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"filter":{"status":["on","soon"],"tag":"paid"},"change":{"days":3},"dry":true}'POST/clients/{name}/remove删除客户——放入回收站 30 天全部
参数
name路径中- 客户名称或其 id
application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/clients/order-88123/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POST回收站4
GET/trash已删除的客户只读
application/json{
"at": 1793754000,
"days": 30,
"clients": [
{
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"gone": 1793751100,
"purge": 1796343100,
"until": 1796342400,
"external": "88123",
"tags": ["paid"],
"contact": "@anna",
"note": "",
"devices": 2,
"taken": false
}
]
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/trash" \
-H "Authorization: Bearer $VELI_TOKEN"POST/trash/{id}/restore从回收站恢复全部
链接和设备不变。名称被占用——taken。响应是完整的客户。
参数
id路径中- 回收站中客户的 id
application/json{
"done": 1,
"client": {
"at": 1793754000,
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null },
"disabled": false,
"link": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"list": [
{
"id": "vk_3fA9c2…",
"kind": "veli",
"os": "Android",
"added": 1793750520,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"kind": "app",
"os": "iOS",
"added": 1793751000
}
],
"lines": [
{
"node": "de-1",
"kind": "Reality",
"line": "vless://…@203.0.113.10:8443?security=reality…#de-1 · Reality"
}
],
"meta": { "order": "88123" },
"page": "https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"apps": {
"Happ": "happ://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb",
"v2rayNG": "v2rayng://install-sub?url=…",
"Hiddify": "hiddify://import/…",
"…": "…",
"Veli": "veli://add/https://panel.example.com/s/kV0pX7wQ2mLr9sTb"
}
}
}错误
400 none- 没有这个名称的客户、节点或分组
400 taken- 该名称已被占用
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/restore" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTPOST/trash/{id}/remove从回收站彻底删除全部
之后再也无法恢复。
参数
id路径中- 回收站中客户的 id
application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/trash/c_Ab3dE5fG7hJ9/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTPOST/trash/clear清空回收站全部
所有已删除的客户——彻底清除。done——原有多少个。
application/json{ "done": 4 }错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/trash/clear" \
-H "Authorization: Bearer $VELI_TOKEN" -X POST事件流1
GET/events事件流:供没有自己地址的系统使用只读
参数
after查询中- 上一次响应的 last;0——从事件流开头
wait查询中- 没有新事件时等待多少秒:0–25
types查询中- 只要这些事件,用逗号分隔
limit查询中- 每次多少个事件,1–1000;不填为 100
application/json{
"at": 1793754000,
"events": [
{
"seq": 1041,
"id": "evt_mV3xQ8rT2kLp",
"event": "client.added",
"at": 1793750460,
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"changed": 1793750460,
"seen": 1793753400,
"note": "",
"contact": "@anna",
"until": 1796342400,
"devices": 3,
"held": 2,
"veli": 1,
"speed": 0,
"added": 1793750400,
"bytes": 1288490188,
"status": "on",
"group": "",
"limit": 0,
"reset": "never",
"used": 0,
"next": 0,
"external": "88123",
"tags": ["paid", "month"],
"wait": 0,
"first": 1793750520,
"left": { "days": 30, "bytes": null }
}
}
}
],
"last": 1041
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/events?after=1040&wait=25&types=client.added,client.expired&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"概览、统计、设备5
GET/overview概览:客户、设备、节点、流量、事件只读
application/json{
"at": 1793754000,
"clients": {
"total": 148,
"active": 131,
"expired": 9,
"expiring": 6,
"limited": 1,
"paused": 1
},
"devices": { "veli": 96, "other": 187 },
"online": 74,
"traffic": 5841203482112,
"top": [
{ "name": "order-88123", "bytes": 41231564800 }
],
"nodes": [
{
"name": "de-1",
"host": "203.0.113.10",
"reported": "203.0.113.10",
"address": "",
"port": 443,
"up": true,
"seen": 1793753990,
"connected": 31,
"protocols": ["Veli", "Reality"],
"ports": [
{ "kind": "veli", "label": "Veli", "port": 443 },
{ "kind": "reality", "label": "Reality", "port": 8443 }
],
"version": "1.8.0",
"behind": false,
"disabled": false,
"main": false,
"added": 1791158400,
"devices": 58,
"traffic": 912680550400
}
],
"events": [
{ "kind": "expiring", "count": 6 },
{ "kind": "silent", "node": "nl-1", "since": 1793753400 }
]
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/overview" \
-H "Authorization: Bearer $VELI_TOKEN"GET/stats面板的每日流量:总计和各节点只读
参数
days查询中- 多少天:7、30 或 90;不填为 30
application/json{
"at": 1793754000,
"days": ["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"],
"total": [612368384000, 640942080000, 702545920000, 655360000000, 598933504000, 683671552000, 214748364800],
"nodes": [
{
"name": "de-1",
"bytes": [311385128960, 322122547200, 354334801920, 330712481792, 300647710720, 343597383680, 107374182400]
}
],
"top": [
{ "name": "order-88123", "bytes": 1288490188 }
],
"online": 74
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"GET/devices所有客户的所有设备只读
application/json{
"at": 1793754000,
"devices": [
{
"id": "vk_3fA9c2…",
"client": "order-88123",
"kind": "veli",
"app": "Veli",
"os": "Android",
"added": 1793750520,
"seen": 1793753940,
"bytes": 1073741824
},
{
"id": "a1b2c3d4e5f6",
"client": "order-88123",
"kind": "app",
"app": "Happ",
"os": "iOS",
"added": 1793751000,
"seen": 1793753700
}
],
"by_app": { "Veli": 96, "Happ": 120, "v2rayN": 67 },
"by_os": { "Android": 140, "iOS": 80, "Windows": 63 }
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/devices" \
-H "Authorization: Bearer $VELI_TOKEN"GET/requests最近的订阅请求只读
参数
client查询中- 只看这个客户的请求
limit查询中- 最近多少条;不填为 200,最多 2000
application/json{
"at": 1793754000,
"requests": [
{
"at": 1793753700,
"client": "order-88123",
"ip": "198.51.100.7",
"app": "Happ",
"code": 200,
"page": false
}
]
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/requests?client=order-88123&limit=50" \
-H "Authorization: Bearer $VELI_TOKEN"GET/log操作日志:令牌和控制台做过什么、从哪里做的全部
参数
who查询中- 令牌名称或 root——只看它的操作
what查询中- clients、nodes、groups、integrations、plugins 或 backups
q查询中- 记录中的词,例如客户名称
before查询中- 早于此时间,unix 时间:下一页
after查询中- 晚于此时间,unix 时间
application/json{
"at": 1793754000,
"more": false,
"names": ["root", "cabinet"],
"kept": 20000,
"entries": [
{
"at": 1793753700,
"name": "cabinet",
"token": true,
"from": "198.51.100.7",
"what": "client add order-88123",
"kind": "clients",
"names": ["order-88123"],
"fields": []
},
{
"at": 1793752200,
"name": "root",
"token": false,
"from": null,
"what": "token add cabinet clients",
"kind": "integrations",
"names": [],
"fields": []
}
]
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/log?who=cabinet&what=clients" \
-H "Authorization: Bearer $VELI_TOKEN"节点6
GET/nodes所有节点只读
application/json{
"at": 1793754000,
"nodes": [
{
"name": "de-1",
"host": "203.0.113.10",
"reported": "203.0.113.10",
"address": "",
"port": 443,
"up": true,
"seen": 1793753990,
"connected": 31,
"protocols": ["Veli", "Reality"],
"ports": [
{ "kind": "veli", "label": "Veli", "port": 443 },
{ "kind": "reality", "label": "Reality", "port": 8443 }
],
"version": "1.8.0",
"behind": false,
"disabled": false,
"main": false,
"added": 1791158400,
"devices": 58,
"traffic": 912680550400
}
],
"kinds": [
{ "kind": "reality", "label": "Reality", "port": 8443, "udp": false },
{
"kind": "shadowsocks",
"label": "Shadowsocks",
"port": 8388,
"udp": false
},
{ "kind": "hysteria2", "label": "Hysteria2", "port": 8443, "udp": true }
]
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/nodes" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes添加节点全部
application/json{ "name": "de-2", "protocols": "reality,shadowsocks:9388" }application/json{
"command": "sudo veli panel attach https://panel.example.com --protocols reality,shadowsocks:9388 --token -",
"token": "Hq3Zr8vT1kLm…"
}错误
400 name- 名称为空、超过 40 个字符、含控制字符,是 c_ 加 12 个字符的形式,或是 API 的词:bulk、find
400 taken- 该名称已被占用
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/nodes" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"name":"de-2","protocols":"reality,shadowsocks:9388"}'GET/nodes/{name}单个节点只读
参数
name路径中- 节点名称
application/json{
"name": "de-1",
"host": "203.0.113.10",
"reported": "203.0.113.10",
"address": "",
"port": 443,
"up": true,
"seen": 1793753990,
"connected": 31,
"protocols": ["Veli", "Reality"],
"ports": [
{ "kind": "veli", "label": "Veli", "port": 443 },
{ "kind": "reality", "label": "Reality", "port": 8443 }
],
"version": "1.8.0",
"behind": false,
"disabled": false,
"main": false,
"added": 1791158400,
"devices": 58,
"traffic": 912680550400,
"at": 1793754000,
"sni": "www.samsung.com"
}错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/nodes/de-1" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes/{name}修改节点全部
参数
name路径中- 节点名称
application/json{
"change": { "address": "de1.example.com", "disabled": false }
}application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
400 main- 迷你面板的主节点不能停用,也不能移除
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/nodes/de-1" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"change":{"address":"de1.example.com","disabled":false}}'GET/nodes/{name}/stats节点的每日流量只读
与客户相同:日期按 UTC,字节为双向合计。
参数
name路径中- 节点名称
days查询中- 多少天:7、30 或 90;不填为 30
application/json{
"days": ["2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04"],
"bytes": [0, 52428800, 104857600, 314572800, 209715200, 419430400, 188743680]
}错误
404 none- 请求的内容不存在,或调用未知
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/nodes/de-1/stats?days=7" \
-H "Authorization: Bearer $VELI_TOKEN"POST/nodes/{name}/remove移除节点全部
它的链接从订阅中消失。迷你面板的主节点不能移除——main。
参数
name路径中- 节点名称
application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
400 main- 迷你面板的主节点不能停用,也不能移除
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/nodes/de-2/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POST分组4
GET/groups客户分组只读
application/json{
"at": 1793754000,
"groups": [
{
"name": "europe",
"nodes": ["de-1", "nl-1"],
"protocols": null,
"clients": 42
}
],
"nodes": ["de-1", "nl-1", "fi-1"],
"kinds": [
{ "kind": "veli", "label": "Veli" },
{ "kind": "reality", "label": "Reality" }
]
}错误
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/groups" \
-H "Authorization: Bearer $VELI_TOKEN"POST/groups添加分组全部
nodes 和 protocols 取自“GET groups”响应中的 nodes 和 kinds 列表;null——全部。
application/json{
"group": {
"name": "europe",
"nodes": ["de-1", "nl-1"],
"protocols": null
}
}application/json{ "done": 1 }错误
400 name- 名称为空、超过 40 个字符、含控制字符,是 c_ 加 12 个字符的形式,或是 API 的词:bulk、find
400 taken- 该名称已被占用
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/groups" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"group":{"name":"europe","nodes":["de-1","nl-1"],"protocols":null}}'POST/groups/{name}修改分组全部
请求体是完整的分组,与添加时相同。
参数
name路径中- 分组名称
application/json{
"group": {
"name": "europe",
"nodes": null,
"protocols": ["veli"]
}
}application/json{ "done": 1 }错误
400 none- 没有这个名称的客户、节点或分组
400 bad- 值超出范围,或分组、节点不存在。field 指明字段,max——上限
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/groups/europe" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"group":{"name":"europe","nodes":null,"protocols":["veli"]}}'POST/groups/{name}/remove删除分组全部
其客户保留——不属于任何分组,可用所有节点和协议。done——分组中原有多少客户。
参数
name路径中- 分组名称
application/json{ "done": 42 }错误
400 none- 没有这个名称的客户、节点或分组
401 token- 没有令牌,或令牌已撤销、已过期。它是否还在,在面板服务器上用 veli token list 查看
403 rights- 令牌没有相应权限:例如只有「全部」才能删除客户。用 GET me 查看权限
429 wait- 令牌每分钟超过 300 次请求,或该地址 15 分钟内用错令牌十次。等待 Retry-After 所写的秒数
500 db- 面板无法保存更改——请用同一个键重试
curl -s "$VELI/groups/europe/remove" \
-H "Authorization: Bearer $VELI_TOKEN" -X POSTOpenAPI 架构与自己的客户端
面板提供整个 API 的架构,OpenAPI 3.1。面板的测试会把它与代码对照:不存在架构之外的调用。可据此用您的语言生成客户端,Postman、Insomnia、n8n 等系统也能直接导入。
curl -s "$VELI/openapi.json" \
-H "Authorization: Bearer $VELI_TOKEN" -o veli-openapi.jsonnpx openapi-typescript veli-openapi.json -o veli-api.d.ts # types for TypeScript
npx @openapitools/openapi-generator-cli generate -i veli-openapi.json -g python -o veli_client # a Python client令牌和 Webhook 不能通过 API 创建:只能由控制台创建(veli token add、veli webhook add)。
状态
on- 正常:期限在计,流量充足
soon- 正常,但期限将在 3 天内结束——该提醒了
limit- 本周期流量用完:链接能打开,但在重置或设定新限额之前无法连接
off- 期限已过:链接可以打开并显示“订阅已到期”,但无法连接。续期后即可再次连接
paused- 被手动或系统停用;期间有效期照常计算
waiting- 期限等待首次连接:礼品或“提前购买”
列表和事件中
id- c_ 加 12 个字符——永久不变:重命名不会改变它。可在路径中代替名称:clients/c_Ab3dE5fG7hJ9。在您那边请保存它,而不是名称
name- 名称,1–40 个字符,每位客户各不相同;不能是 c_ 加 12 个字符的形式——id 就长这样
external- 外部 ID——您那边的客户 ID;为空表示没有。它不唯一:一个人可能买两份订阅,所以搜索返回的是列表
tags- 标签
status- on、soon、limit、off、paused 或 waiting——见上文
until- 期限结束时间,unix 时间;0——永久,或期限仍在等待首次连接
wait, first- 期限中有多少秒从首次连接起算(0——不等待);应用首次获取订阅的时间(0——尚未获取)
left- 剩余量:days 和 bytes;null——不限期限、不限流量
devices, held, veli- 允许的设备数、所有应用已占用数、其中 Veli 设备数
speed- Veli 每个方向的速度,Mbit/s;0 为不限
limit, reset, used, next- 流量限额(字节,0 为不限)、重置周期(never、day、week 或 month,按 UTC)、本周期已用量、下一周期开始时间
group- 分组;为空表示无分组
bytes- 累计总流量
seen, changed- 应用最近一次请求订阅的时间(精确到 10 分钟,0——没有);最近一次更改(手动或系统)
note, contact, added- 备注、联系方式、添加时间
只在单个客户中——GET clients/<name>
at- 响应生成的时间,unix 时间
link- 订阅链接——是机密:只交给客户本人
page- 供浏览器打开的订阅页面,带应用按钮
apps- 各应用的“添加到 …”链接
list- 设备:id,kind——veli(Veli 密钥)或 app(其他应用的 HWID),os,added;Veli 设备还有 bytes
lines- 各节点的普通协议链接:node、kind、line
meta- 您系统的字段
disabled- true——客户已停用
应用按钮
apps——现成的“添加到 …”链接:Happ、v2rayNG、Hiddify、Streisand、sing-box、Clash、Shadowrocket、v2RayTun 和 Veli。网站和邮件把它们放进按钮。聊天和邮件里的按钮只接受 https://,所以更适合用 page——订阅页面,上面已经有各应用的按钮。按 IP 访问、使用自签证书的面板,其他应用无法校验链接——那里只有 Veli。
剩余量
left——还剩多少:days——期限的整天数(等待中的客户为其等待期),bytes——本周期的字节;字段为 null——不限期限或不限流量。这是给您的界面现成的一句话:“还剩 12 天和 30 GB”。
可以修改什么——change 的字段
days- 续期多少天:从期限结束时算起,已过期的从现在算起;小于零——缩短。对于等待首次连接的客户——延长或缩短等待期。新客户的天数写在 change 旁边,null 为永久。±1–36500
until- 精确的期限结束时间,unix 时间;0——永久。不能与 days 同时使用。设为过去的时间——期限立即结束
start- first_use——期限从应用首次请求订阅时开始;now——等待中的客户立即开始计期
name- 新名称——只能给一个客户;id、链接、设备和流量保持不变
disabled- true——停用:链接打不开,设备从节点上移除,期限照常计算;false——启用
relink- true——更换链接:旧链接失效,普通协议的账号换新,Veli 设备保留
devices- 允许的设备数,1–100
speed- Mbit/s,0–100000;0 为不限
limit, reset, zero- 流量限额(字节)、重置周期,true——从零开始计算
group- 分组名称;为空表示无分组
external- 外部 ID,最多 128 个字符;为空则删除
tags- 标签——整个列表重写:最多 20 个,每个最多 32 个字符
tags_add, tags_remove- 添加和移除标签,其余保留——批量修改时很方便
meta- 您系统的字段——全部重写:最多 20 个;键为拉丁字母、数字和 _ . -,最多 40 个字符;值最多 500 个字符
note, contact- 备注最多 300 个字符,联系方式最多 100 个
过长的值不会被截断,而是返回带字段和上限的 bad 错误——{"error": "bad", "field": "change.devices", "max": 100}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。
过滤与排序
不带参数时,GET clients 返回所有客户。每个参数都会缩小列表,可以组合使用。
external, tag- 外部 ID、标签
status- 用逗号分隔:on,soon,limit,off,paused,waiting
group- 分组;空值——无分组
q- 名称、备注、联系方式或外部 ID 中的词,不区分大小写
until_before, until_after- 期限结束早于、晚于——unix 时间;永久的两边都不计入
changed_since- 自此时间起被手动或系统更改
devices- none、some、full——没有设备、有设备、名额全部占满
used_over- 已用量不少于限额的这一比例,%
seen_before- 应用自此时间起没有获取过订阅——或从未获取过
sort- name、until、added、used、changed;前面加“-”——倒序
limit, cursor- 每页 1–1000 条,游标取自上一页的 next
curl -s "$VELI/clients?status=soon&sort=until&limit=100" \
-H "Authorization: Bearer $VELI_TOKEN"curl -s "$VELI/clients?q=anna&tag=paid&group=europe" \
-H "Authorization: Bearer $VELI_TOKEN"curl -s "$VELI/clients?devices=full&used_over=90" \
-H "Authorization: Bearer $VELI_TOKEN"curl -s "$VELI/clients?seen_before=1791158400&status=on" \
-H "Authorization: Bearer $VELI_TOKEN"分页
- 带 limit 时,响应为 {at, clients, total, next}:total——符合过滤条件的总数,next——下一页的游标,null——这是最后一页。
- 游标是排序中的位置,而不是页码:翻页期间添加或删除的客户不会让其他客户错位——不会有人出现两次,也不会有人漏掉。
- 请求下一页时使用相同的过滤条件和 sort,只改变 cursor。
{
"at": 1793754000,
"clients": [
{"id": "c_Ab3dE5fG7hJ9", "name": "order-88123", "status": "soon", "…": "…"}
],
"total": 412,
"next": "eyJrIjoxNzk0MDAwMDAwfQ"
}这是谁的客户
用户向客服发来链接或设备密钥——找到对应的客户。链接可以是完整的,也可以只是它的秘密部分——/s/ 之后的部分。
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"link": "kV0pX7wQ2mLr9sTb"}'
curl -s "$VELI/clients/find" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"device": "a1b2c3d4e5f6"}'按过滤条件批量修改
POST clients/bulk 用 filter 代替 names,会修改过滤条件选中的所有客户——要么全部,要么一个不改。先看看会涉及谁:dry: true 返回数量和前 100 个名称,不做任何更改。
curl -s "$VELI/clients/bulk" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"filter": {"tag": "promo-nov", "status": ["on", "soon"]}, "change": {"tags_add": ["thanked"]}, "dry": true}'
curl -s "$VELI/clients/bulk" \
-H "Authorization: Bearer $VELI_TOKEN" \
-H "content-type: application/json" \
-d '{"names": ["order-88123", "c_Ab3dE5fG7hJ9"], "change": {"group": "europe"}}'{
"done": 0,
"matched": 412,
"names": ["order-88123", "order-88124", "…"]
}- 空过滤条件——bad:这样就不会意外修改“所有人”。对所有有效客户——status: ["on", "soon"]。
- tags_add 和 tags_remove 修改标签而不动其他标签——例如,标记已发送邮件的客户。
- 批量删除——用 remove: true 代替 change,需要“全部”权限。被删除的客户在回收站中保留 30 天。