ローカルAPI

ローカルAPIはOBSオーバーレイと同じサーバー（オーバーレイポート）を共有します。このPC上で動作しているプログラムからのリクエストにのみ応答し、アクセストークンによる認証が必要です。

ローカルAPIを有効化する

トークンを生成 をクリックするとトークンが再生成されます。古いトークンを使用しているすべてのスクリプトは即座に切断されます（オーバーレイや配信接続には影響ありません）。トークンは32〜256文字の英数字、ハイフン、アンダースコアを使って手動で指定することも可能です。

待機ポートは同じカード内の 共有サーバーポート で変更できます。新しいポートはVfinityを再起動した後に有効になります。起動時にポートが使用されていた場合、Vfinityは別の空きポートを自動選択し、実際に使用されているアドレスがカードに表示されます。

リクエストの検証ルール

すべてのHTTPリクエストおよびWebSocket接続には、以下のヘッダーが必要です：

Authorization: Bearer YOUR_TOKEN

他のPCからのリクエスト、トークンが欠落または誤っているリクエスト、あるいはブラウザの Origin ヘッダーを含むリクエストはすべて拒絶されます。最後のルールにより、同一PC上で開かれたWebページであってもAPIを直接呼び出すことはできません。ヘッダーを設定できるデスクトップスクリプトやツールを使用してください。

別のPCのOBSにオーバーレイへのアクセスを許可してもAPIがネットワークに公開されることはなく、オーバーレイのアクセスキーはAPIトークンとしては機能しません。

APIが応答するにはVfinityが起動している必要があります（システムトレイに格納されていても構いません）。アプリを終了すると待機は停止します。

HTTP経由でリクエストを送信する

すべての POST リクエストには Content-Type: application/json を指定してください。ボディのサイズは最大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トリガー と トリガー名 を設定し、その名前を /api/trigger にPOSTします。名前は大文字と小文字を区別せずに照合されます。

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がトリガーを受理したことを意味します。イベントがオフの場合、一時停止中の場合、またはクールダウン中の場合は動作しないため、実際に何が実行されたかを確認したい場合はWebSocketの actionResult を監視してください。

コマンドを実行する

コマンドとは、ホットキー、クイックデッキのパッド、コマンドステップが使用するのと同じ名前付きアクションです。GET /api/state を実行すると現在利用可能なコマンドの一覧を取得できます（一部のコマンドは対応する機能が起動している間だけ存在します）。

{ "name": "control.panic" }
{ "name": "deck.press", "args": "拍手" }
{ "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}} という応答はリクエストがキューに追加されたことを意味し、まだLIVEに参加したわけではありません。/api/state の tiktok 部分、またはWebSocketの tiktokStatus を監視してください（VfinityがLIVEに参加すると room.state が "connected" になります）。

WebSocketでリアルタイム受信する

同じ Authorization ヘッダーを付けて ws://127.0.0.1:21424/api/ws に接続します。HTTPと同様のリクエストを任意の requestId を付けて送信できるほか、配信上で発生したイベントがリアルタイムでストリーミングされます。

// 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" }

それぞれに対して1つの応答が返されます：{"type":"response","requestId":"2","data":{"ok":true}}。

Vfinityから送信されるメッセージ

コンボの一部であるギフト（giftType が 1）は、コンボの継続中に更新通知を送信します。Vfinityと同様に、repeatEnd が false でないときのみ処理を行ってください。タイムスタンプはUnixミリ秒です。

配信データはリアルタイムのみです。過去のデータは再送されないため、読み込みが遅いクライアントはメッセージを取りこぼす可能性があります。

制限とエラーコード

通常バックアップでは安全のためトークンは除外され、復元時はAPIが無効の状態で読み込まれます。トークンを保持したい場合はバックアップ時に パスワードやトークンを含める にチェックを入れてください。

逆方向に接続する（Trigger API）

詳細 の下にある トリガーAPI カードは、接続の向きを逆にします：Vfinityがクライアントとして、あなたが起動したWebSocketサーバーへ接続します。ゲームや外部ボットなど、すでに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 は接続状態やイベント数を返します。

あなたのサーバーにアクセスできるプログラムはすべてこれらのコマンドを実行できるため、サーバーをこのPC内に限定するか、手前に認証を挟んで保護してください。

関連ページ