POST/api/v1/media/credentials
App Bearer与八项公共头,始终HTTPS及原JWE协议JSON 响应接入指南 ↗

申请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项检查范围见统一协议验证。