文档/如何接入/自建面板/调用·6 / 9

调用

请求体和响应都是 JSON,只有二维码是 SVG 或 PNG。地址中的名称按 encodeURIComponent 编码,也可以用客户 id 代替名称。点击某个调用,即可看到参数、请求体、响应和现成的命令。地址和令牌可以放在变量里:

在您的服务器上
VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…

令牌、架构、MCP3

GET/me当前令牌:名称、权限、有效期、API 版本任意
响应 200application/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只读
响应 200application/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" }
  }
}
响应 200application/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
响应 200application/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" }
响应 200application/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}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。

响应 200application/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
响应 200application/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}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。

响应 200application/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”链接的二维码,而不是订阅链接
响应 200image/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.svg
GET/clients/{name}/stats客户的每日流量只读

日期按 UTC,从最早到今天;字节为双向合计。

参数

name路径中
客户名称或其 id
days查询中
多少天:7、30 或 90;不填为 30
响应 200application/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
响应 200application/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
响应 200application/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" }
响应 200application/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}:否则您的系统无法得知保存的内容不对。新客户会在响应中完整返回,包括链接。

响应 200application/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
响应 200application/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已删除的客户只读
响应 200application/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
响应 200application/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 POST
POST/trash/{id}/remove从回收站彻底删除全部

之后再也无法恢复。

参数

id路径中
回收站中客户的 id
响应 200application/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 POST
POST/trash/clear清空回收站全部

所有已删除的客户——彻底清除。done——原有多少个。

响应 200application/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
响应 200application/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概览:客户、设备、节点、流量、事件只读
响应 200application/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
响应 200application/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所有客户的所有设备只读
响应 200application/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
响应 200application/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 时间
响应 200application/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所有节点只读
响应 200application/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" }
响应 200application/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路径中
节点名称
响应 200application/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 }
}
响应 200application/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
响应 200application/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路径中
节点名称
响应 200application/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客户分组只读
响应 200application/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
  }
}
响应 200application/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"]
  }
}
响应 200application/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路径中
分组名称
响应 200application/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 POST

OpenAPI 架构与自己的客户端

面板提供整个 API 的架构,OpenAPI 3.1。面板的测试会把它与代码对照:不存在架构之外的调用。可据此用您的语言生成客户端,Postman、Insomnia、n8n 等系统也能直接导入。

把架构保存到文件
curl -s "$VELI/openapi.json" \
  -H "Authorization: Bearer $VELI_TOKEN" -o veli-openapi.json
TypeScript 类型或现成的 Python 客户端
npx 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
3 天内到期的客户——按期限排序
curl -s "$VELI/clients?status=soon&sort=until&limit=100" \
  -H "Authorization: Bearer $VELI_TOKEN"
在 europe 分组的已付费客户中按词搜索
curl -s "$VELI/clients?q=anna&tag=paid&group=europe" \
  -H "Authorization: Bearer $VELI_TOKEN"
名额全部占满且流量已用 90 %——可以建议他们续期或增加设备
curl -s "$VELI/clients?devices=full&used_over=90" \
  -H "Authorization: Bearer $VELI_TOKEN"
仍在有效期内、但自 10 月 1 日起没有连接过的客户
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 天。