Local API

Local API ใช้งานเซิร์ฟเวอร์ร่วมกับโอเวอร์เลย์ OBS บนพอร์ตของโอเวอร์เลย์ โดยจะตอบรับเฉพาะโปรแกรมที่ทำงานอยู่บนคอมพิวเตอร์เครื่องนี้เท่านั้น และต้องแนบโทเค็นการเข้าถึงของคุณมาด้วยเสมอ

เปิดใช้งาน Local API

ปุ่ม สร้างโทเค็นใหม่ จะสร้างโทเค็นชุดใหม่ขึ้นมาแทนที่ สคริปต์เดิมทั้งหมดที่ใช้โทเค็นเก่าจะถูกตัดการเชื่อมต่อทันที ส่วนโอเวอร์เลย์และการเชื่อมต่อไลฟ์จะยังคงทำงานต่อไป คุณยังสามารถพิมพ์โทเค็นที่ต้องการได้เอง โดยต้องมีความยาว 32 ถึง 256 ตัวอักษร ประกอบด้วยตัวอักษร ตัวเลข ขีดกลาง หรือขีดล่าง

พอร์ตจะอยู่ในการ์ดเดียวกันในช่อง พอร์ตเซิร์ฟเวอร์ที่ใช้ร่วมกัน พอร์ตใหม่จะมีผลหลังจากรีสตาร์ท Vfinity หากพอร์ตถูกใช้งานอยู่ตอนเริ่มแอป Vfinity จะเลือกพอร์ตอื่นและแสดงที่อยู่ที่ใช้งานจริงบนการ์ด

การตรวจสอบคำขอ

ทุกคำขอ HTTP และทุกการเชื่อมต่อ WebSocket ต้องแนบส่วนหัว (Header) นี้:

Authorization: Bearer YOUR_TOKEN

คำขอจะถูกปฏิเสธเมื่อส่งมาจากคอมพิวเตอร์เครื่องอื่น เมื่อโทเค็นไม่ถูกต้องหรือสูญหาย หรือเมื่อมีส่วนหัว Origin ของเบราว์เซอร์แนบมาด้วย กฎข้อสุดท้ายนี้หมายความว่าหน้าเว็บบนเบราว์เซอร์จะไม่สามารถเรียก API ได้ แม้จะเป็นเว็บที่เปิดบนคอมพิวเตอร์เครื่องนี้ก็ตาม จึงต้องใช้สคริปต์เดสก์ท็อปหรือเครื่องมือที่สามารถกำหนดส่วนหัวได้

การเปิดให้ OBS บนคอมพิวเตอร์เครื่องอื่นเข้าถึงโอเวอร์เลย์ได้ ไม่ได้เป็นการเปิด API สู่เครือข่าย และคีย์การเข้าถึงโอเวอร์เลย์ไม่ใช่โทเค็น API

Vfinity ต้องเปิดทำงานอยู่จึงจะตอบรับ API ได้ (แม้จะย่ออยู่ในถาดระบบก็นับว่าทำงานอยู่) หากปิดแอป จะไม่มีสิ่งใดรับฟังคำขอ

ส่งคำขอผ่าน HTTP

แนบ Content-Type: application/json มากับทุกคำขอ POST โดยเนื้อหามีขนาดได้สูงสุดไม่เกิน 64 KiB

# ตรวจสอบว่าสามารถรันคำสั่งอะไรได้บ้าง
curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:21424/api/state

# เพิ่มเวลา 30 วินาทีในตัวจับเวลาซับบาธอน
curl -X POST http://127.0.0.1:21424/api/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"timer.add","args":30}'

$headers = @{ Authorization = "Bearer YOUR_TOKEN" }

# ตรวจสอบว่าสามารถรันคำสั่งอะไรได้บ้าง
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 YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"raid_alarm","data":{"message":"Raid incoming","level":3}}'

แต่ละฟิลด์ใน data จะกลายเป็นตัวแปรเทมเพลตที่ขั้นตอนของอีเวนต์นำไปใช้ได้ เช่น ขั้นตอนเสียงพูดที่มี {message} จะอ่านว่า "Raid incoming" รองรับข้อความ ตัวเลข และค่าจริง/เท็จ (บูลีน) โดยไม่รองรับออบเจกต์ซ้อนหรืออาร์เรย์ ชื่อฟิลด์ต้องขึ้นต้นด้วยตัวอักษร และนับสูงสุด 50 ฟิลด์แรก

การตอบกลับ {"ok":true} หมายถึง Vfinity ยอมรับทริกเกอร์เข้าสู่ระบบแล้ว แต่อีเวนต์ที่ปิดใช้งาน อยู่ในสถานะหยุดพัก หรือติดคูลดาวน์ จะยังคงไม่ทำงาน ดังนั้นโปรดรับฟัง actionResult บน WebSocket หากต้องการทราบว่าขั้นตอนใดทำงานเสร็จสิ้นจริง

สั่งรันคำสั่ง

คำสั่งคือแอคชันเดียวกับที่ปุ่มลัด ปุ่มควิกเด็ค และขั้นตอนคำสั่งเรียกใช้ GET /api/state จะแสดงรายการคำสั่งที่บิลด์นี้รองรับในขณะนั้น เนื่องจากบางคำสั่งจะมีให้ใช้เฉพาะเมื่อส่วนของแอปนั้นกำลังทำงานอยู่

{ "name": "control.panic" }
{ "name": "deck.press", "args": "Applause" }
{ "name": "giveaway.draw" }
{ "name": "sceneCard.showBrb" }
{ "name": "mapping.trigger", "args": "YOUR_EVENT_ID" }

mapping.trigger จะรันอีเวนต์ของคุณเสมือนว่าทริกเกอร์ทำงานจริง และตอบกลับด้วยจำนวนรอบที่เริ่มทำงาน โดยรับค่าเป็น ID อีเวนต์ หรือชื่อของทริกเกอร์ API หากต้องการดู ID ให้คลิกขวาที่อีเวนต์ในแท็บ อีเวนต์ แล้วเลือก คัดลอก ID อีเวนต์

ดูรายการคำสั่งทั้งหมดพร้อมอาร์กิวเมนต์ได้ใน คำสั่ง

เชื่อมต่อ TikTok LIVE จากสคริปต์

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

คำตอบ {"ok":true,"result":{"accepted":true}} หมายถึงคำขอเข้าสู่คิวแล้ว ไม่ได้หมายความว่าเข้าร่วมไลฟ์สำเร็จแล้ว ให้เฝ้าดูส่วน tiktok ของ /api/state หรือ tiktokStatus บน WebSocket: ค่า room.state จะกลายเป็น "connected" เมื่อ Vfinity เข้าร่วมห้องไลฟ์สำเร็จ

รับฟังข้อมูลผ่าน WebSocket

เชื่อมต่อไปยัง ws://127.0.0.1:21424/api/ws พร้อมแนบส่วนหัว Authorization เดียวกัน คุณสามารถส่งคำขอแบบเดียวกับ 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 YOUR_TOKEN' },
});

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) จะส่งข้อมูลอัปเดตระหว่างที่คอมโบดำเนินอยู่ ควรตอบสนองต่อของขวัญเมื่อ repeatEnd ไม่ใช่ false เช่นเดียวกับที่ Vfinity ทำ การประทับเวลาเป็น Unix milliseconds

การสตรีมข้อมูลเป็นแบบสดเท่านั้น: ไม่มีการเล่นย้อนหลัง และไคลเอนต์ที่อ่านข้อมูลช้าเกินไปอาจพลาดข้อความได้

ขีดจำกัดและข้อผิดพลาด

การสำรองข้อมูลทั่วไปจะไม่รวมโทเค็น และการกู้คืนจะปิดใช้งาน API ไว้ ให้ทำเครื่องหมายที่ รวมรหัสผ่านและโทเค็น เมื่อสำรองข้อมูลหากต้องการเก็บไว้

ให้ Vfinity เชื่อมต่อไปหาคุณแทน

การ์ด Trigger API ซึ่งอยู่ในส่วน ขั้นสูง เช่นกัน จะสลับทิศทางการเชื่อมต่อ: Vfinity จะเชื่อมต่อไปในฐานะไคลเอนต์สู่เซิร์ฟเวอร์ WebSocket ที่คุณเปิดไว้ เหมาะสำหรับเซิร์ฟเวอร์ที่มีอยู่แล้ว เช่น เกมหรือบอท

เปิดสวิตช์ Trigger 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 จะตอบกลับด้วยสถานะการเชื่อมต่อและจำนวนอีเวนต์

สิ่งใดก็ตามที่เข้าถึงเซิร์ฟเวอร์ของคุณได้จะสามารถรันคำสั่งเหล่านี้ได้ จึงควรเปิดเซิร์ฟเวอร์ไว้บนคอมพิวเตอร์เครื่องนี้ หรือติดตั้งระบบยืนยันตัวตนไว้ข้างหน้าเซิร์ฟเวอร์ของคุณ

อ่านเพิ่มเติม