朱雀 API — 播放器 SDK 接口文档

概述

/key/*	密钥服务	ZQMF 加密视频的密钥获取、设备绑定、统计
/metrics/*	指标服务	SDK 播放质量上报、Dashboard 查询
/health	健康检查	返回 {"status":"ok"}

认证方式

/key/acquire	HMAC 签名	sign = HMAC-SHA256(appSecret, videoId+deviceFp+timestamp)
/metrics/report	appId 验证	需合法 appId
其他接口	Bearer Token	Header: Authorization: Bearer {ADMIN_TOKEN}

指标上报

POST/metrics/report

SDK 播放结束或异常时调用。一次播放 = 一条记录。异常立即上报，正常等结束汇总。

公开（验证 appId）

{
  "appId": "your_app_id",          // 必填
  "videoId": "video_abc123",       // 必填
  "deviceFp": "sha256:a3f2...",     // 必填
  "sessionId": "play_7f3a2b1c",     // 必填
  "result": "SUCCESS",              // 必填: SUCCESS | FAILED
  "errorCode": 0,                   // FAILED 时必填
  "errorMessage": "",
  "firstFrameMs": 1180,             // 首帧时间（毫秒）
  "totalDurationMs": 15000,
  "playDurationMs": 14200,
  "bufferingCount": 2,
  "bufferingDurationMs": 800,
  "stutterRatio": 0.053,
  "device": {
    "model": "Pixel 6", "manufacturer": "Google",
    "osVersion": "Android 13", "apiLevel": 33,
    "cpu": "Tensor", "ram": 8192,
    "codecH264": true, "codecH265": true
  },
  "network": {
    "type": "WiFi", "carrier": "中国移动",
    "downBandwidthKbps": 50000, "signalDbm": -45
  },
  "playback": {
    "sourceType": "ZQMF", "engineType": "IJK",
    "codecMode": "HARDWARE", "resolution": "1280x720",
    "bitrate": 1135
  }
}

IP 地址由服务端自动获取，无需客户端传入。

查询 API

所有查询接口需要 Admin Token

GET/metrics/overview

概览：成功率 / 首帧 / 卡顿率 / 播放量 + 环比

Admin Token

参数	类型	说明
appId	string	可选不传=全局
from / to	string	可选 ISO 8601，默认最近 24h

GET/metrics/trend

趋势图数据，按小时或天聚合

Admin Token

参数	类型	说明
interval	string	可选 hour（默认）\| day

GET/metrics/errors

错误类型分布 TOP N

Admin Token

参数	类型	说明
limit	int	可选默认 10

GET/metrics/errors/{code}/devices

某错误类型的受影响设备（第二层下钻）

Admin Token

参数	类型	说明
network	string	可选 4G / 5G / WiFi
carrier	string	可选运营商筛选
limit / offset	int	可选分页

GET/metrics/devices

设备兼容性排行

Admin Token

参数	类型	说明
sortBy	string	可选 failRate \| plays \| firstFrame

GET/metrics/records

播放记录列表（多维筛选）

Admin Token

参数	类型	说明
videoId / deviceFp / result / errorCode	—	可选筛选
limit / offset	int	可选分页

GET/metrics/records/{id}

单条记录完整详情 + 自动根因分析

Admin Token

{
  // ... 完整上报数据 ...
  "rootCause": "弱网环境导致分片下载超时",
  "suggestion": "启用低码率优先策略"
}

rootCause 和 suggestion 由服务端自动生成。

密钥服务

POST/key/acquire

获取 ZQMF 视频解密密钥

HMAC 签名

{
  "appId": "app_id", "videoId": "video_id",
  "deviceFp": "sha256:...", "timestamp": 1774132800,
  "nonce": "random16", "sign": "hmac_hex"
}

GET/key/stats

调用量统计（计费用）

Admin Token

错误码

Code	含义	常见原因
700	网络超时	弱网/CDN 不可达
701	流读取错误	连接中断
900	解码失败	设备不支持编码/低内存
-10000	格式不支持	非标格式
-38	非法状态	播放器异常

🔥 朱雀 API

概述

认证方式

指标上报

查询 API

密钥服务

错误码