命令与 API - Social Stream Ninja

机器人命令

内置机器人命令

Social Stream Ninja 包含多个内置命令，观众可以在聊天中使用，你也可以通过 API 触发。

命令	说明	如何启用
`!joke`	随机回复一个极客风格的冷笑话	通过扩展菜单开关启用
`hi`	自动欢迎在聊天中说“hi”的人	通过扩展菜单开关启用
`!cycle`	启用后，允许观众更改 OBS 场景	通过扩展菜单开关启用

注意： 只有正确配置自动回复器，并且你有权在相应平台发布消息时，机器人命令才会生效。

自动回复配置

要使自动回复器正常工作：

确保你已登录相应平台（YouTube、Twitch 等）
确保聊天窗口可见（未最小化）
先尝试手动发送测试消息，确认权限
在扩展菜单中启用相应命令的开关

要隐藏触发自动回复时出现的蓝色调试栏，可在启动 Chrome 时使用 --silent-debugger-extension-api 标志。

服务器 API

概述

Social Stream Ninja 提供强大的 API，让你可以通过编程控制直播配置的各个方面。API 服务器既可向你的配置发送命令，也可监听从整合的聊天服务传入的消息。

叠加层管理

控制精选消息、清除叠加层，并调整直播内容的外观。

Webhook 集成

接收来自 Stripe、Ko-Fi 和 Buy Me A Coffee 等第三方服务的事件。

消息导出

将聊天消息导出到文件，或通过 webhook（POST）转发，以实现自定义集成。

必要设置（全局设置 → 机制）：

🎮 远程控制（StreamDeck/Bitfocus）： 启用 “启用扩展的远程 API 控制” （开关 1）— 连接到 频道 1
📡 聊天监听器（Python/Node 应用）： 启用开关 1 + “将聊天消息发送到 API 服务器” （开关 3）— 连接到 频道 4

请参阅完整 API 文档，了解详细的设置指南和代码示例。

API 端点与连接方式

HTTP GET/POST

https://io.socialstream.ninja/{sessionID}/{action}/{target}/{value}

适合从 Stream Deck 或自定义脚本发送简单命令。

WebSocket

wss://io.socialstream.ninja:443

用于实时双向通信，支持自动重连。

如果希望保持点对点连接而不启用 WebSocket 模式，可以使用 Social Stream Ninja WebRTC SDK。它包含 Node 和浏览器示例，例如 Social Stream Ninja 监听器.

服务器发送事件（SSE）

https://io.socialstream.ninja/sse/{sessionID}

用于接收服务器的单向实时更新。

频道系统

API 使用频道系统进行消息路由：

	- Channel 1: Remote control commands (default for StreamDeck/Bitfocus)
	- Channel 2: Dock page output
	- Channel 3: Extension receives commands from Dock
	- Channel 4: Chat messages from Extension (use this to receive Twitch/YouTube chat!)
	- Channel 5: Waitlist/giveaway communication
	- Channels 6-9: Reserved for future use

使用所需频道进行连接：

// To receive chat messages (listen on channel 4):
wss://io.socialstream.ninja/join/SESSION_ID/4

// To send commands (channel 1 default):
wss://io.socialstream.ninja/join/SESSION_ID

常用 API 命令

操作	说明	示例
`sendChat`	向所有已连接的聊天平台发送消息	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	向所有平台发送 URL 编码的消息	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	从叠加层中清除精选消息	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	显示队列中的下一条消息	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	切换消息自动精选功能	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	屏蔽某个特定平台上的用户	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	将外部内容作为聊天消息发送	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	按消息 ID 置顶停靠面板中已有的消息，或置顶完整的消息对象。需要 `dock.html` 在同一个会话中保持打开。	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	按消息 ID 取消停靠面板中已有消息的置顶。对于带标签的停靠面板，请使用 target 字段/路径段。	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	将停靠面板中第一条置顶消息设为精选。	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	移除第一个有效的等候名单条目，或以下参数指定编号的有效条目： `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	高亮显示第一个有效的等候名单条目，或以下参数指定编号的有效条目： `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	停止或恢复接收新的等候名单报名，不会清除现有名单。 `openentries` 和 `resumeentries` 是以下命令的别名： `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	从等候名单/抽奖中随机选出一个或多个获胜者	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	从运行中的 Social Stream 页面/应用下载当前等候名单，格式为 TSV 文件	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	开启/关闭抽奖模式，或在以下条件成立时切换： `value` 等于 `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	设置等候名单页面显示的等候名单或抽奖标题消息	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	清空等候名单并重新开放报名	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

查看完整 API 文档

交互式 API 沙盒

使用我们的交互式沙盒试用 API，轻松访问所有命令和功能：

如需在 OBS 中使用更精简的直播控制按钮，请使用 Social Stream 控制停靠面板并遵循 OBS 设置指南.

打开 API 沙盒

测试命令

在安全环境中试用所有 API 命令

生成代码

获取 HTTP、WebSocket 和 SSE 的代码示例

查看结果

查看命令的实时响应

创建测试

生成随机内容的测试消息

注意： 记得替换 SESSIONID 为你在 Social Stream Ninja 中实际使用的会话 ID！

StreamDeck 与 Companion

StreamDeck 集成

Social Stream Ninja 通过多种方式与 StreamDeck 集成：原生 HTTP 操作和 Bitfocus Companion 集成。

HTTP/API 方式

使用 StreamDeck 的“Website”操作，并启用“GET request in background”，即可直接向 API 发送命令。

Bitfocus Companion

原生集成，提供预设操作、实时反馈，以及用于动态内容的变量。

Companion 集成

Bitfocus Companion 可通过 WebSocket 或 HTTP API 对 Social Stream Ninja 进行强大的控制。

操作	说明	API 方式
清除精选消息	从叠加层中移除当前精选消息	WebSocket/HTTP
队列中的下一条	显示下一条排队的消息	WebSocket/HTTP
切换自动显示	启用/禁用自动精选消息	WebSocket/HTTP
发送聊天消息	向所有已连接的平台发送消息	WebSocket/HTTP

动态变量

featured_message - 当前精选消息文本
featured_username - 当前精选用户的用户名
queue_size - 队列中的消息数量

设置资源

获取 Companion 模块文档

AI 集成

AI 聊天机器人模式

Social Stream Ninja 提供全面的 AI 集成，通过 AI 聊天回复、内容审核等功能增强直播。可根据需要选择本地或云端 AI 提供商。

自动聊天回复

让 AI 自动与你的观众互动、回答问题，即使你专注于自己的内容，也能保持对话活跃。

内容审核

使用 AI 识别可能有害的消息，并按你的偏好自动处理，辅助管理聊天。可选择不阻止模式或严格阻止模式。

RAG 搜索

检索增强生成使 AI 能搜索你的自定义知识库，提供准确且贴合你内容的回答。

多个机器人实例

运行不同的机器人实例，满足不同用途：公开聊天机器人、私人一对一机器人、审查机器人，甚至能看能听的多模态 AI 搭档。

支持的 AI 提供商

Social Stream Ninja 支持多种 AI 提供商，从完全本地运行的浏览器/运行时模型到托管 API：

Ollama（原生本地 API）

免费、注重隐私的自托管 AI 模型，通过 Ollama 自身的 API 在你的电脑上运行。

本地 Gemma 4

先将模型文件镜像到自己的资源服务器，再在浏览器中运行 Gemma 4；SSN 的 largefiles 服务器目前不包含 Gemma 资源。

本地 Qwen 3.5

使用自己托管的模型文件在浏览器中运行 Qwen 3.5，在本地生成私密回复。

ChatGPT / OpenAI

OpenAI API，包括现代聊天和实时语音模型。

Google Gemini

Google Gemini 模型，包括目前的 Gemini 2.5 文本和实时多模态选项。

DeepSeek

针对对话任务优化、高效且经济的 AI 模型。

xAI (Grok)

xAI Grok API，包括使用临时客户端密钥时的实时语音会话。

AWS Bedrock

来自不同提供商的企业级 AI 模型，包括 Claude 和 Llama。

OpenRouter

通过统一的 API 接口访问多种 AI 模型。

Groq

兼容 OpenAI 的低延迟聊天推理，实现快速的对话回复。

自定义 API（兼容 OpenAI）

连接到 llama.cpp、LM Studio、vLLM 或其他任何兼容 OpenAI 的端点。

注意： Ollama 使用自身的原生 API。对于 llama.cpp、LM Studio、vLLM 或其他兼容 OpenAI 的服务器，请选择 自定义 API.

文本转语音集成

Social Stream Ninja 为机器人消息和精选聊天内容提供全面的 TTS 支持：

系统 TTS

免费的内置 TTS，使用操作系统的语音合成器。

Kokoro

免费的本地 TTS，使用 WebGPU/CPU 运行，适合注重隐私的用户。

Kitten TTS

轻量级的浏览器 TTS，下载小型模型后可在本地生成语音。

ElevenLabs

优质语音合成，提供自然且可自定义的声音。

Google Cloud TTS

高质量声音，提供丰富的语言和自定义选项。

Gemini（预览版 TTS）

Google 的预览版神经语音模型，可选择声音和语言。

Speechify

由 AI 驱动的文本转语音，具备自然的声音转换能力。

OpenAI TTS

OpenAI 语音合成，可选择声音、模型，并可使用兼容端点。

注意： TTS 功能需要在 OBS 中打开相应的叠加层页面。不同 TTS 提供商有不同的声音选项、延迟，以及价格或硬件要求。

机器人实例与叠加层

Social Stream Ninja 为不同使用场景提供多个机器人实例：

机器人类型	URL	说明
主聊天机器人	`/bot.html`	主机器人叠加层，可选 TTS 和公开聊天回复
私人聊天界面	`/chatbot.html`	专用的一对一机器人页面，不与主机器人共享 RAG 数据集或聊天历史
审查机器人	（在后台运行）	自动过滤、净化或屏蔽传入消息
AI 搭档	`/cohost.html`	能够查看屏幕、听取音频并互动的多模态 AI

设置 AI 集成

按照以下步骤，在当前菜单中设置 AI 集成：

1

选择并连接 LLM 提供商

在以下位置选择提供商： 配置 LLM 服务提供商 ，并填写对应字段：

Ollama： 在本地安装，并按需设置端点
本地 Gemma / 本地 Qwen： 使用托管的浏览器模型资源，并可覆盖模型文件夹；Qwen 可使用 SSN largefiles，Gemma 则需要你自己的镜像文件夹
ChatGPT、Gemini、DeepSeek、xAI、Groq、OpenRouter、Bedrock： 添加 API 密钥和首选模型
自定义 API： 输入兼容 OpenAI 的端点、模型 ID，以及可选的 API 密钥

2

测试所选聊天机器人

使用内置的 测试所选聊天机器人 按钮，在开播前验证提供商、模型和凭据。

3

配置机器人行为

自定义机器人在聊天中的行为：

启用 LLM AI 聊天机器人
设置机器人名称、触发词和回复频率限制
选择将回复发回聊天，还是仅发送到机器人叠加层页面
添加自定义指令，指定语气、角色和管理规则

4

启用可选附加功能

开启所需的机器人相关功能：

为机器人回复启用 TTS，并选择提供商
为以下页面选择固定时长、按消息长度或 TTS 后自动隐藏的行为： /bot.html；使用 clearBotOverlay 进行手动清除
启用 RAG 并上传文档，让回答参考相关知识
启用审查机器人进行内容审核或严格屏蔽
打开 /bot.html, /chatbot.html，或 /cohost.html ，按需在 OBS 或浏览器中使用

详细文档

完整设置说明和更深入的 TTS 内容，请参阅以下指南：

AI 聊天机器人设置指南本地 AI TTS 指南用于自动回复的机器人账号 Ollama 官方下载

MIDI 与快捷键控制

MIDI 集成

使用 MIDI 控制器、键盘快捷键或带 MIDI 插件的 StreamDeck 控制 Social Stream Ninja。

设置要求

在扩展设置中启用 MIDI 支持
安装虚拟 MIDI 回环设备（例如 loopMIDI）
配置 MIDI 控制器或 StreamDeck MIDI 插件

CC 编号	值	操作	说明
102	1	向聊天发送“1”	快速回应
102	2	向聊天发送“LUL”	表情回应
102	3	讲个笑话	触发机器人回复
102	4	清除叠加层	移除精选消息

提示： MIDI 控制最适合实体控制器，也可通过虚拟 MIDI 设备触发。

快捷键支持

使用键盘快捷键快速访问常用功能。

可在菜单设置中配置快捷键；当浏览器获得焦点或使用应用时，快捷键可在系统范围内生效。

Webhook 集成

打赏服务

Social Stream Ninja 可以通过 webhook 接收第三方服务的打赏和事件；以下列出几个热门服务：

Stripe

直接通过你的 Stripe 账号处理信用卡打赏。

在此创建付款链接： stripe.com
在 Stripe Dashboard 中，前往 Developers → Webhooks
添加端点： https://io.socialstream.ninja/SESSIONID/stripe
选择事件 checkout.session.completed
添加 &server 到停靠面板 URL

Ko-Fi

接受支持者请你喝咖啡的打赏。

登录你的 Ko-Fi 账号
前往 Webhook 设置
添加 https://io.socialstream.ninja/SESSIONID/kofi 作为 webhook URL
添加 &server 到停靠面板 URL
使用“发送单条打赏测试”按钮进行测试

Buy Me A Coffee

通过热门的 Buy Me A Coffee 平台接受打赏。

登录你的 Buy Me A Coffee 账号
前往 webhook 设置
添加 https://io.socialstream.ninja/SESSIONID/bmac 作为 webhook URL
添加 &server 到停靠面板 URL，以接收事件
支持打赏和会员事件

安全提示： 请保密你的会话 ID，因为任何持有它的人都能向叠加层发送虚假打赏。应将 webhook URL 视为敏感信息。

外部服务集成

Social Stream Ninja 也可以向第三方服务发送数据：

服务	URL 参数	说明
Singular Live	`&singular=IDENTIFIER`	将选定消息发送到 Singular Live，用于精选消息叠加层
H2R	`&h2r=IDENTIFIER`	将选定消息发送到本地 H2R 服务器
通用 POST	`&postserver=URL`	通过 POST 将选定消息发送到自定义端点
通用 PUT	`&putserver=URL`	通过 PUT 将选定消息发送到自定义端点

这些参数应添加到停靠面板页面的 URL 中。

自定义脚本

自定义 JavaScript

你可以通过自定义 JavaScript 代码，创建自己的命令和功能：

使用 custom.js

重命名 custom_sample.js 为文件名 custom.js
编辑文件以添加自定义功能
在本地打开 dock.html 文件以加载 custom.js

此方法可实现复杂的自定义功能和触发器。

自定义叠加层

创建自定义叠加层

你可以从头创建完全自定义的聊天叠加层，匹配直播独特的风格和功能。Social Stream Ninja 提供灵活的基础，供你继续扩展。

从模板开始

先使用我们的叠加层示例模板，了解基础知识：

// View the sample overlay
https://socialstream.ninja/sampleoverlay?session=SESSIONID

这个最简模板只包含叠加层正常运行所需的基本代码。

查看叠加层示例

可自定义的主要功能

在精选消息与显示全部消息之间切换
使用 CSS 自定义外观
为新消息添加自定义动画
实现自己的消息过滤逻辑
使用 JavaScript 添加互动元素

实施步骤

下载叠加层示例 HTML 文件
编辑 HTML 以实现自定义布局
自定义 CSS 以获得所需外观
按需修改 JavaScript，实现自定义行为
将文件保存在本地，作为 OBS 浏览器源使用

计时器 API

远程控制： `timer.html`

计时器页面特意保持精简：一个计时器、可选的操作员控件、警告状态、超时计时和几种视觉样式。

实用操作包括 starttimer, pausetimer, resettimer, timeradd, timersubtract，以及 settimer.

{
  "action": "settimer",
  "value": {
    "seconds": 300,
    "label": "Interview",
    "mode": "countdown",
    "style": "stage",
    "warnSeconds": 60,
    "dangerSeconds": 15
  }
}

如需查询当前计时器状态，请使用 gettimerstate 并附上回调令牌。

{ "action": "gettimerstate", "get": "timer-state-1" }

打开页面时使用 timer.html?session=YOUR_SESSION&server ，即可直接通过 API 服务器控制它。