申请CDN媒体访问凭证¶
请求参数¶
面向App,无业务请求体,不接受用户/会话/对象编号。八项公共头与本站Authorization必填,安装、平台及渠道与会话绑定。始终HTTPS;JSON请求/响应遵循JWE协议,不能因开发固定码允许其他HTTP入口就通过HTTP取得媒体凭证。
只有固定媒体地址协议返回transport=CDN且确实需要联网时才调用;CDN关闭时,合法会话请求返回404/NOT_FOUND。原OSS交付不需要此凭证。
请求示例¶
以下为加密前的请求头示意;按统一JWE封装发送,不使用示例Token进行实际调用。JWE业务body为null,无需额外字段。
POST /api/v1/media/credentials HTTP/1.1
Host: api.example.com
Accept: application/jose
Content-Type: application/jose
Accept-Language: zh-CN
Authorization: Bearer <当前App访问Token>
X-Client-Type: app
X-Platform: android
X-App-Version: 1.0.0
X-App-Build: 1
X-Channel: dev
X-Device-Id: 44444444-4444-4444-8444-444444444444
X-Request-Id: 55555555-5555-4555-8555-555555555555
X-Request-Timestamp: <当前Unix毫秒>
X-Budyoo-Encryption: jwe-v1
<按JWE协议封装的请求>
成功响应¶
HTTP200、Cache-Control:no-store,结果处于原JWE内。以下是解密后的合成示例:
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"origin": "https://media.budyoo.cn",
"headerName": "X-Budyoo-Media-Token",
"token": "bdm_替换为本次媒体凭证",
"expiresAt": "2026-11-17T03:00:00Z"
},
"errors": []
}
| 字段 | 类型/可空 | 说明 |
|---|---|---|
| origin | string,非空 | 唯一允许发送凭证的HTTPS源,与媒体交付项精确一致 |
| headerName | string,非空 | 当前为X-Budyoo-Media-Token |
| token | string,非空 | bdm_开头的256位随机材料,只在账号内存复用,不用于App登录或OSS API |
| expiresAt | UTC时间,非空 | 最长一小时;原会话失效、账号限制或权限变化可提前拒绝,并不延长会话 |
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | INVALID_CLIENT_HEADERS/VALIDATION_FAILED | 公共头或协议不合法 |
| 401 | UNAUTHORIZED | 登录凭证失效、安装不符或会话已撤销 |
| 403 | 原准入/设备/账号限制码 | 沿现有App认证规则 |
| 404 | NOT_FOUND | CDN未启用,不签发无消费者的凭证 |
| 413 | PAYLOAD_TOO_LARGE | 控制JSON整包超过16KiB |
| 426 | HTTPS_REQUIRED | 未使用HTTPS |
| 503 | SERVICE_UNAVAILABLE | 临时凭证索引不可用,不降级匿名或返回假凭证 |
失败结构沿公共协议,固定code不翻译,message按Accept-Language四语生成。
接入说明¶
按需刷新,并发合并;不用后台定时轮询。已有有效公开缓存时无需调用。新凭证不改变固定媒体地址,也不清空有效公开缓存。退出/换号清理凭证与晚到回执;不持久化或记录token。具体地址、请求头、Range与错误处理见固定媒体地址协议。
2026-11-19深圳正式部署环境(上线前阶段,当前运行配置为dev)已启用真实CDN。受信HTTPS/JWE验证了签发、刷新后固定地址及cacheKey不变、其他账号拒绝、退出后旧媒体凭证读取已缓存对象拒绝;共15项公网检查范围见共享契约。既有全量1364项服务器测试(0失败/0错误/1项条件跳过)、新增媒体25项及JS/JWE示例18项为此前后端验证,本次没有重跑Java全量。Flutter真机接入另行验收;客户端不得在OSS请求中携带此凭证。
2026-11-20随统一媒体协议部署后重新通过真实公网签发、刷新、稳定URL/cacheKey、跨账号与退出撤权检查,视频Range同样保留媒体鉴权;服务器完整1390项回归及公网39项检查范围见统一协议验证。