API 文档 v2 · 外部调用版

对外公开 API · 新版 · 强制传入频道ID · 支持多频道 · 有 IP 黑名单保护

🔒

调用说明：v2 版本与 v1 并存，区别是 必须传入 guild_id 参数，不再依赖默认配置频道。
适用于需要同时对接多个频道的场景。所有公开 API 均有 IP 黑名单保护。

📝 与 v1 的主要区别：
1. guild_id 参数从可选变为必填
2. 不传 guild_id 直接返回 400 错误，不再使用默认频道
3. 接口路径变为 /api/public/v2/*

v2 公开 API

语音频道数据

GET /api/public/v2/voice

获取指定频道的语音频道实时概要数据。与 v1 功能相同，但 必须显式传入 guild_id。

请求参数 (Query)

参数	类型	必填	说明
guild_id	string	是	频道 ID（v2 强制必填）

# 请求
curl "https://pd.txpd.cn/bot/api/public/v2/voice?guild_id=512274747283833032"

# 缺少 guild_id 时返回
{ "success": false, "error": "缺少 guild_id 参数", "code": "MISSING_GUILD_ID" }

# 成功响应
{
  "success": true,
  "data": {
    "guild_id": "512274747283833032",
    "channels": [
      {
        "channel_id": "12345678",
        "channel_name": "语音频道A",
        "online_count": 12,
        "members": [...]
      }
    ],
    "total_online": 42,
    "updated_at": "2026-07-04T15:00:00+08:00"
  }
}

# 频道无数据时返回
{ "success": false, "error": "暂无该频道的语音数据", "code": "NO_DATA" }

响应字段

字段	类型	说明
success	boolean	请求是否成功
data.guild_id	string	频道 ID
data.channels	array	有在线成员的语音频道列表
data.total_online	number	语音总在线人数
data.updated_at	string	数据更新时间（ISO 8601）

GET /api/public/v2/online-count

获取指定频道的语音总在线人数，最简格式，适合高频轮询。

参数	类型	必填	说明
guild_id	string	是	频道 ID（v2 强制必填）

# 请求
curl "https://pd.txpd.cn/bot/api/public/v2/online-count?guild_id=512274747283833032"

# 响应
{
  "success": true,
  "data": {
    "guild_id": "512274747283833032",
    "total_online": 42,
    "channel_count": 5,
    "updated_at": "2026-07-04T15:00:00+08:00"
  }
}

响应字段

字段	类型	说明
success	boolean	请求是否成功
data.total_online	number	语音总在线人数
data.channel_count	number	有在线成员的语音频道数
data.updated_at	string	数据更新时间

v1 与 v2 对比速查

特性	v1（老版）	v2（新版）
路径前缀	`/api/public/`	`/api/public/v2/`
guild_id	可选，不传用默认频道	必填
多频道支持	有限（通过参数指定）	完整（每个请求独立指定）
错误处理	缺参时回退默认频道	缺参直接返回 400
IP 黑名单	有	有

💡 迁移建议：如果你的调用方需要同时对接多个频道，建议使用 v2。如果只对接单一默认频道，v1 和 v2 均可使用。