直播能力接入文档

概述

开放平台直播能力面向业务方提供完整的实时音视频直播间, 业务方只需:

1. 用应用 Key 调一次接口签发直播 Token
2. 把 Token 通过 URL 参数传给官方直播间页
3. 在自家页面通过 iframe 嵌入即可

无需关心音视频协议 / 信令服务器 / 边缘节点等基础设施。三种官方直播间形态:

接入流程

1. 控制台注册账号 → 创建应用 → 拿到 sk-live-* Key
2. 在应用详情页订阅直播能力
3. 业务方后端用 sk-live Key 调签发 Token 接口
4. 把 Token 通过 URL 参数传给 iframe, 嵌入自家页面
5. (可选) 监听 iframe postMessage 处理报名 / 咨询等业务事件

鉴权

所有 /api/v1/live/* 接口走 sk-live Bearer Key 鉴权, 在请求头加:

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key 只能由业务方后端持有, 不能暴露到浏览器。浏览器侧只接受签好的直播 Token 或入场凭证 (entry_token)。

签发直播 Token

POST /api/v1/live/tokens

请求示例

curl -X POST https://open.zcode.team/api/v1/live/tokens \\
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "room": "class-2026-001",
    "identity": "viewer-789",
    "name": "张同学",
    "role": "subscriber",
    "ttl_seconds": 7200
  }'

请求字段

响应 (默认)

{
  "code": 0,
  "msg": "ok",
  "data": {
    "token": "eyJhbGciOiJI...",
    "expires_at": 1781600863,
    "websocket_url": "wss://zhibo.yunshee.com"
  }
}

响应 (require_entry=true)

返回的是入场凭证, 浏览器拿它走短信验证, 验证通过后换真直播 Token:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "entry_token": "eyJhbGciOiJI...",
    "require_entry": true,
    "room": "app_xxxxxxxx_class-2026-001",
    "expires_at": 1781594263,
    "websocket_url": "wss://zhibo.yunshee.com"
  }
}

iframe 嵌入

把上一步拿到的 Token 通过 URL 参数传给 iframe:

主播开播台

<iframe
  src="https://live.yunshee.com/host.html?token=PUBLISHER_TOKEN&title=高考志愿填报专场"
  allow="camera; microphone; autoplay"
  style="width:100%;height:100vh;border:0">
</iframe>

观众观看页

<iframe
  src="https://live.yunshee.com/watch.html?token=SUBSCRIBER_TOKEN&nickname=张同学&anchor_name=王老师"
  allow="autoplay"
  style="width:100%;height:100vh;border:0">
</iframe>

会议室

<iframe
  src="https://live.yunshee.com/room?token=YOUR_TOKEN"
  allow="camera; microphone; display-capture; autoplay"
  style="width:100%;height:600px;border:0">
</iframe>

URL 参数

房间管理

通常直接签 Token 就够用 (访问房间时自动创建), 需要预创建 / 主动关闭时用以下接口:

# 创建房间 (可选, 直接签 Token 也会自动创建)
curl -X POST https://open.zcode.team/api/v1/live/rooms \\
  -H "Authorization: Bearer sk-live-xxx" \\
  -H "Content-Type: application/json" \\
  -d '{"name":"class-2026-001","max_participants":50}'

# 查询房间
curl "https://open.zcode.team/api/v1/live/rooms/class-2026-001" \\
  -H "Authorization: Bearer sk-live-xxx"

# 关闭房间 (踢出所有人)
curl -X DELETE "https://open.zcode.team/api/v1/live/rooms/class-2026-001" \\
  -H "Authorization: Bearer sk-live-xxx"

进场短信验证

当业务方需要在观众进直播间前收集实名手机号时, 签 Token 时传 require_entry: true, 拿到的就是入场凭证 (而不是直播 Token):

• 浏览器把入场凭证传给 watch.html
• 观众看到进场表单 (昵称 + 手机号 + 验证码)
• 开放平台自动发送短信验证码 (业务方无需对接短信通道)
• 验证通过后, 浏览器自动换得真直播 Token 并连接
• 同时下发 pass_token 写入 localStorage, 7 天内同设备同手机号免重复验证

整个流程对业务方透明 — 只需在签 Token 时多传一个标志, 不需要写一行 SMS 代码。

商品 / 报名扩展

当业务方传入 products_url 参数后, 直播间会自动开启商品扩展:

• 主播端顶部出现 🛒 推商品 按钮, 可向所有观众弹商品促销卡
• 观众端右侧出现 商品 入口, 可打开商品列表 / 咨询 / 报名
• 观众的操作通过 postMessage 发回父页面, 业务方自行处理 (写销售线索 / 跳转报名页 等)

products_url 接口规范

业务方需自己提供一个返回如下格式的 GET 接口:

{
  "items": [
    { "id": 1, "name": "VIP 月卡", "price_range": "¥99", "desc": "30 天无限观看", "thumb": "https://..." },
    { "id": 2, "name": "VIP 年卡", "price_range": "¥888" }
  ]
}

postMessage 协议 (iframe → 父页面)

父页面监听示例

window.addEventListener('message', e => {
  if (e.data?.source !== 'live-room/watch') return;
  switch (e.data.type) {
    case 'signup':
      // 观众点商品促销卡的"立即报名" — 把信息落到自家销售线索表
      fetch('/api/your-system/leads', { method: 'POST', body: JSON.stringify(e.data) });
      break;
    case 'product_click':
      // 观众点商品列表的"咨询" — 用作埋点
      break;
    case 'leave':
      // 观众离开直播间
      break;
  }
});

错误码