83. 开发者 API 速查 · 玄武屏使用手册

玄武屏提供 REST API 与 WebSocket API，供开发者集成到自己的系统。本节是开发者快速参考。

认证

1. API Key

账户中心 → API → 创建 API Key
   ↓
得到：
  ApiKey: xwp_xxxxxxxxxxxxxxxx
  ApiSecret: yyyyyyyyyyyyyyyy

2. 请求签名

每次请求带 Header：

Authorization: Bearer <jwt-token>

JWT 由 ApiKey + ApiSecret 签发。SDK 自动处理。

REST API

资源管理

GET    /api/decks                # 列出我的演示
POST   /api/decks                # 创建新演示
GET    /api/decks/:id            # 获取详情
PUT    /api/decks/:id            # 更新
DELETE /api/decks/:id            # 删除
GET    /api/decks/:id/versions   # 历史版本

演示文稿操作

POST   /api/decks/:id/share        # 创建分享链接
POST   /api/decks/:id/duplicate    # 复制演示
POST   /api/decks/:id/export       # 导出（PDF / 图片 / 离线包）
GET    /api/decks/:id/preview      # 缩略图

多端联动

POST   /api/rooms                  # 创建演示房间
GET    /api/rooms/:id              # 获取房间状态
POST   /api/rooms/:id/join         # 加入房间
POST   /api/rooms/:id/start        # 开始演示
POST   /api/rooms/:id/end          # 结束演示
GET    /api/rooms/:id/participants # 参与者列表

课堂数据

POST   /api/classroom/:id/quiz     # 发起答题
POST   /api/classroom/:id/distribute # 内容下发
GET    /api/classroom/:id/data     # 学情数据
GET    /api/classroom/:id/report   # AI 报告

触发器

POST   /api/triggers/:room-id      # 触发演示行为
GET    /api/triggers/:room-id/state # 查询当前状态

详见「47. 外部触发」。

请求 / 响应格式

请求

{
  "title": "我的产品发布会",
  "industry": "enterprise",
  "language": ["zh", "en"]
}

响应

{
  "code": 200,
  "data": {
    "id": "deck-abc123",
    "title": "我的产品发布会",
    "createdAt": "2026-04-26T10:00:00Z"
  },
  "message": null
}

错误响应

{
  "code": 401,
  "data": null,
  "message": "API Key 无效",
  "errorCode": "XWP-601"
}

WebSocket API

连接

const ws = new WebSocket(
  'wss://api.bahuangqi.com/ws?token=jwt-token'
)

订阅房间

ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'room:abc123'
}))

监听事件

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  switch (msg.type) {
    case 'page-change':
      console.log('翻到第', msg.page, '页')
      break
    case 'student-answer':
      console.log('学生答题：', msg.data)
      break
  }
}

发送指令

ws.send(JSON.stringify({
  type: 'go-to-page',
  room: 'abc123',
  page: 5
}))

详见「36. 同步机制」。

SDK

JavaScript / TypeScript

npm install @bahuangqi/xwp-sdk

import { XwpClient } from '@bahuangqi/xwp-sdk'

const client = new XwpClient({
  apiKey: 'xwp_...',
  apiSecret: '...'
})

// 创建演示
const deck = await client.decks.create({
  title: '我的演示',
  pages: [...]
})

// 创建房间
const room = await client.rooms.create({
  deckId: deck.id
})

// 监听事件
room.on('student-answer', (data) => {
  console.log(data)
})

Python

pip install bahuangqi-xwp-sdk

from bahuangqi_xwp import XwpClient

client = XwpClient(api_key='xwp_...', api_secret='...')
deck = client.decks.create(title='我的演示')

其它语言

Java / Kotlin
Go
C# / .NET
PHP

Webhooks

POST /api/webhooks
{
  "url": "https://your-server.com/xwp-webhook",
  "events": ["deck.created", "room.ended"]
}

事件举例：

{
  "event": "room.ended",
  "data": {
    "roomId": "abc123",
    "duration": 1800,
    "participants": 47,
    "report": "https://..."
  }
}

速率限制

接口	限制
标准 API	60 次 / 分钟
创建 / 修改	30 次 / 分钟
大文件上传	5 次 / 分钟
WebSocket 连接	10 / 分钟

超限响应 429 Too Many Requests。

接入示例

集成到 LMS

1. LMS 用户点击玄武屏课件
2. LMS 后端调玄武屏 API 创建房间
3. 返回房间 URL 给学生
4. 学生进入房间上课
5. 课后 LMS 后端拉取学情数据
6. 写入 LMS 学生档案

集成到 CRM

1. 销售在 CRM 选客户
2. CRM 调玄武屏 API 创建客户化演示
3. 销售用演示讲方案
4. 演示数据回传 CRM
5. 用于销售漏斗分析

集成到 IoT 系统

1. IoT 平台监测某指标超阈值
2. 调玄武屏 trigger API
3. 大屏切换到告警页面
4. 数字人通报告警

API 状态页

https://status.bahuangqi.com/api

开发者支持

文档：https://docs.bahuangqi.com
API 沙箱：https://sandbox.bahuangqi.com
工单：账户中心
社区：开发者论坛

详见「89. 社区与生态」。

下一节讲性能配置与调优。