本地 API

本地 API 与 OBS 叠加层共享同一个服务器，位于叠加层端口上。它仅响应运行在本机上的程序，且请求必须携带你的访问令牌。

启用本地 API

生成令牌会替换当前令牌。所有仍在使用旧令牌的脚本会立即断开连接，而叠加层和你的直播连接则不受影响。你也可以输入自定义令牌：长度为 32 到 256 个字符，可包含字母、数字、短横线或下划线。

端口设置位于同一卡片中的共用服务器端口。更改端口将在重启 Vfinity 后生效。如果在启动时该端口已被占用，Vfinity 会自动选择其他可用端口，且卡片中会显示实际使用的地址。

请求校验机制

每个 HTTP 请求与每个 WebSocket 连接都需要携带以下请求头：

Authorization: Bearer 你的访问令牌

在以下情况下请求会被拒绝：请求来自其他电脑、令牌缺失或不正确、或者携带了浏览器的 Origin 请求头。最后一条规则意味着网页无法调用此 API，即使该网页在当前电脑的浏览器中打开也是如此。请使用能够自定义请求头的桌面脚本或工具。

为其他电脑上的 OBS 开启叠加层访问权限并不会将 API 暴露给网络，叠加层访问密钥也不是 API 令牌。

必须保持 Vfinity 处于运行状态，API 才会响应。最小化到系统托盘同样属于运行中；退出应用后，服务器将停止监听。

通过 HTTP 发送请求

每次发送 POST 请求时都必须携带 Content-Type: application/json。请求体最大支持 64 KiB。

# 查询当前可运行的内容
curl -H "Authorization: Bearer 你的访问令牌" http://127.0.0.1:21424/api/state

# 为加钟计时器增加 30 秒
curl -X POST http://127.0.0.1:21424/api/command \
  -H "Authorization: Bearer 你的访问令牌" \
  -H "Content-Type: application/json" \
  -d '{"name":"timer.add","args":30}'

$headers = @{ Authorization = "Bearer 你的访问令牌" }

# 查询当前可运行的内容
Invoke-RestMethod -Uri http://127.0.0.1:21424/api/state -Headers $headers

# 为加钟计时器增加 30 秒
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:21424/api/command `
  -Headers $headers -ContentType "application/json" `
  -Body '{"name":"timer.add","args":30}'

触发你的事件

为事件添加 API 触发 并指定一个触发名称，然后将该名称 POST 到 /api/trigger。名称匹配不区分大小写。

curl -X POST http://127.0.0.1:21424/api/trigger \
  -H "Authorization: Bearer 你的访问令牌" \
  -H "Content-Type: application/json" \
  -d '{"name":"raid_alarm","data":{"message":"Raid incoming","level":3}}'

data 中的每个字段都会转换为该事件步骤可用的模板变量，例如带有 {message} 的朗读步骤会朗读“Raid incoming”。文本、数字以及布尔值均可透传；嵌套对象和列表不支持透传。字段名称必须以字母开头，且最多处理前 50 个字段。

返回 {"ok":true} 表示 Vfinity 已接受该触发。如果事件已被关闭、处于暂停状态，或正处于冷却期，则依然不会执行任何动作。如果你需要确认实际执行情况，请通过 WebSocket 监听 actionResult。

运行指令

指令是快捷键、Quick Deck 按键板以及指令步骤所使用的同名具名操作。GET /api/state 会列出当前版本此刻提供的指令，因为部分指令只有在对应应用模块处于运行状态时才存在。

{ "name": "control.panic" }
{ "name": "deck.press", "args": "Applause" }
{ "name": "giveaway.draw" }
{ "name": "sceneCard.showBrb" }
{ "name": "mapping.trigger", "args": "你的事件ID" }

mapping.trigger 会如同触发器被触发一样运行你的某项事件，并返回已启动的运行次数。它接受事件的 ID 或 API 触发器的名称。要获取事件 ID，请在事件标签页中右键点击该事件，然后选择复制事件 ID。

完整指令及其参数已在指令中列出。

通过脚本连接 TikTok LIVE

{
  "name": "tiktok.connect",
  "args": { "username": "yourname", "autoRejoin": true, "waitForLive": true }
}

响应 {"ok":true,"result":{"accepted":true}} 表示请求已进入队列，并不代表已经成功加入直播间。请观察 /api/state 中的 tiktok 部分，或监听 WebSocket 上的 tiktokStatus：一旦 Vfinity 进入直播间，room.state 会变为 "connected"。

监听 WebSocket

使用相同的 Authorization 请求头连接到 ws://127.0.0.1:21424/api/ws。你可以发送与 HTTP 相同的请求（每个请求均可附带自定义的 requestId），Vfinity 会将直播间发生的所有事件实时流式推送给你。

// npm install ws
const WebSocket = require('ws');

const socket = new WebSocket('ws://127.0.0.1:21424/api/ws', {
  headers: { Authorization: 'Bearer 你的访问令牌' },
});

socket.on('open', () => {
  socket.send(JSON.stringify({ type: 'command', name: 'timer.add', args: 30, requestId: '1' }));
});

socket.on('message', (raw) => {
  const message = JSON.parse(raw);
  if (message.type === 'event' && message.event === 'gift') {
    console.log(`${message.data.nickname} sent ${message.data.giftName}`);
  }
  if (message.type === 'response') console.log(message.requestId, message.data);
});

发送的消息格式

{ "type": "state", "requestId": "1" }
{ "type": "command", "name": "timer.add", "args": 30, "requestId": "2" }
{ "type": "trigger", "name": "raid_alarm", "data": {}, "requestId": "3" }

每个请求都会收到一条回复：{"type":"response","requestId":"2","data":{"ok":true}}。

Vfinity 发送的消息类型

连击礼物（giftType 为 1）在观众持续点击时会多次发送更新消息。与 Vfinity 一样，建议仅在 repeatEnd 不为 false 时执行对应操作。时间戳为 Unix 毫秒时间戳。

该数据流仅为实时推送：不会回放历史数据，读取速度过慢的客户端可能会丢失消息。

限制与错误码

常规备份不会包含访问令牌，恢复备份后 API 默认保持关闭。若要在备份中保留令牌，请在备份时勾选包含密码和令牌。

让 Vfinity 反向连接到你的服务

同样位于高级下的 触发 API 卡片支持反向连接：Vfinity 作为客户端连接到你运行的 WebSocket 服务器。这适用于已存在的服务器，例如自建游戏或机器人。

开启 触发 API，输入 WebSocket 主机 与 WebSocket 端口，然后点击 连接 API。随后你的服务器可以发送：

{ "type": "trigger", "name": "raid_alarm", "data": { "message": "Raid incoming" } }
{ "type": "command", "name": "timer.add", "args": 30, "requestId": "abc-1" }
{ "type": "request", "requestType": "event_list", "requestId": "abc-2" }

附带 requestId 的指令会收到类似 {"type":"response","requestType":"command","requestId":"abc-1","data":{"name":"timer.add","ok":true}} 的回复。event_list 会返回所有配置了 API 触发器的事件、其包含的步骤以及是否已开启；stats 则返回连接状态与事件计数。

任何能访问你服务器的客户端都可以运行这些指令，因此请确保服务器仅监听本机，或者在其前端配置你自己的身份验证。

相关内容