批量获取媒体交付信息¶
请求参数¶
2026-11-20已部署统一的RoutedMediaDelivery结构,不再要求X-Media-Delivery。不传、cdn-v1、oss-v1均返回本页结构;CDN/OSS/API由服务端选择,不返回旧delivery或单项message。唯一正式部署环境仍使用dev配置,客户端应按统一协议解析,设备验收单独记录。
用于用户上传的头像、相册、动态图片、音视频、举报证据和私密明信片照片。原业务成功响应已经按统一协议直接提供地址与顶层mediaDelivery,首屏通常无需本接口;仅在持有业务path需要重新授权(如OSS签名到期)时按需调用。Java检查原领域权限并生成交付信息,文件正文由返回的通道读取,不由本接口传输。
八项公共请求头全部必填;真实Bearer与安装绑定,X-Client-Type=app,平台ios/android。请求和包含签名的响应均使用统一JWE,正式模式强制HTTPS;响应Cache-Control:no-store。无路径及查询参数。请求整包含JWE最多16KiB,每IP10r/s、突发10、最多4并发,仍叠加普通及全站限制。
| JSON字段 | 类型 | 必填 | 限制 |
|---|---|---|---|
| paths | string[] | 是 | 1–50项,每项1–200字符;重复路径按首次出现顺序合并 |
仅支持下表精确相对路径。UUID须为完整标准形式,不接受绝对URL、OSS Key、暂存目录、后台路径、URL编码、查询参数、片段、额外斜线或图片处理参数。任何路径格式不合法时整批400,尚未签发其他条目。
| 相对路径 | 权限规则 |
|---|---|
/api/v1/media/avatars/{id} |
上传头像仅本人可读,允许注册中账号;不能拿他人的图片ID申请 |
/api/v1/media/album-photos/{id} |
本人有效照片,保留资料状态及软删除检查 |
/api/v1/media/user-avatars/{userId} |
先检查双向屏蔽;本人取当前已保存绑定,他人只取最后通过头像 |
/api/v1/media/user-albums/{userId}/{photoId} |
先检查双向屏蔽,始终只认可当前已审公开相册快照,即使查看者为本人 |
/api/v1/media/post-photos/{id} |
未绑定仅上传者;绑定后检查原动态可见性及审核状态 |
/api/v1/media/community-files/{id} |
原音视频/证据权限;证据仅上传者,其他按动态可见性与暂存到期判断 |
/api/v1/media/community-files/{id}/poster |
与原文件相同权限,未生成封面返回不可见,不能伪造图片 |
/api/v1/media/postcard-photos/{id} |
复用暂存本人/参与者、首信审核、回信审核与有效期规则 |
除第一行本人上传头像外,均要求完成注册及服务端普通业务准入。应用内默认头像和迁移前仍保存在数据库的旧明信片字节显式返回transport=API;目前深圳旧明信片BYTEA已迁空。默认头像、国家旗帜、兴趣目录图标等内置或目录资产不在本次OSS下载迁移范围。
请求示例¶
以下为JWE封装前的逻辑JSON;实际请求头为application/jose,不可直接把明文用于prod。
curl -X POST 'https://api.budyoo.cn/api/v1/media/downloads' \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
-H 'Accept-Language: zh-CN' -H 'Authorization: Bearer <accessToken>' \
-H 'X-Client-Type: app' -H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' -H 'X-App-Build: 1' -H 'X-Channel: dev' \
-H 'X-Device-Id: 4d4ae3ea-6a4a-4f34-a292-8e94551851d7' \
-H 'X-Request-Id: 632e403d-fbf8-43a1-8dc6-d87c20371a2e' \
-H 'X-Request-Timestamp: <当前Unix毫秒>' \
--data '{"paths":["/api/v1/media/avatars/33333333-3333-4333-8333-333333333333"]}'
成功响应¶
HTTP200,data为按首次出现顺序排列的条目数组,与聚合响应的mediaDelivery[]完全同构;本接口不额外增加顶层mediaDelivery。单个无权或已删除资源返回access=DENIED、transport=NONE,其余合法资源继续返回。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": [
{
"path": "/api/v1/media/avatars/33333333-3333-4333-8333-333333333333",
"url": "https://media.budyoo.cn/media/avatars/33333333-3333-4333-8333-333333333333.png",
"access": "PRIVATE",
"expiresAt": null,
"cacheKey": "budyoo-media:v1:example-opaque-resource-key",
"cacheMaxAgeSeconds": 0,
"code": "SUCCESS",
"transport": "CDN",
"requestHeaders": {"X-Budyoo-Media-Path": "/api/v1/media/avatars/33333333-3333-4333-8333-333333333333"},
"authorization": {
"origin": "https://media.budyoo.cn",
"headerName": "X-Budyoo-Media-Token",
"credentialPath": "/api/v1/media/credentials"
}
},
{
"path": "/api/v1/media/album-photos/44444444-4444-4444-8444-444444444444",
"url": null,
"access": "DENIED",
"expiresAt": null,
"cacheKey": "/api/v1/media/album-photos/44444444-4444-4444-8444-444444444444",
"cacheMaxAgeSeconds": 0,
"code": "NOT_FOUND",
"transport": "NONE",
"requestHeaders": {},
"authorization": null
}
],
"errors": []
}
| data[]字段 | 类型/可空 | 含义 |
|---|---|---|
| path | string,非空 | 输入业务相对路径;不以下载URL代替媒体ID或保存字段 |
| url | string或null | 当前CDN/OSS HTTPS或API相对地址;拒绝及不可用为null |
| access | string,非空 | PUBLIC、PRIVATE、API、DENIED、UNAVAILABLE;PUBLIC不代表CDN匿名可读 |
| expiresAt | ISO 8601 UTC或null | OSS_SIGNED最晚有效时间,最长五分钟;其他通道为null;CDN凭证另有期限 |
| cacheKey | string,非空 | 对象的不透明稳定键,与域名、签名和凭证无关;API/不可用条目为path |
| cacheMaxAgeSeconds | integer,非空 | PUBLIC为86400,其余0;PRIVATE不得落盘 |
| code | string,非空 | SUCCESS、NOT_FOUND、FORBIDDEN等单项固定码,不翻译 |
| transport | string,非空 | CDN、OSS_PUBLIC、OSS_SIGNED、API、NONE |
| requestHeaders | object,非空 | CDN含X-Budyoo-Media-Path;其他为空对象,不在此返回凭证 |
| authorization | object或null | 仅CDN有origin、headerName和credentialPath,定义见统一字段表 |
服务端CDN关闭时,仍使用上述字段返回OSS_PUBLIC或OSS_SIGNED。下载项不含旧delivery或message;顶层成功message按Accept-Language返回中英日韩、未知回退英文。客户端逐项检查code、access与transport,不能仅因HTTP200显示所有资源。
CDN请求携带返回的静态路径头与独立媒体凭证,且只在精确origin一致时附加;每次联网(含缓存命中、HEAD和Range)仍检查业务权限。OSS_SIGNED为仅GET的短效能力,允许有效期内的字节Range,不用于HEAD/PUT/DELETE;完整地址原样使用,不追加参数或附带本站身份。OSS_PUBLIC使用服务端允许的公开副本,API沿原文件鉴权。完整缓存与凭证刷新见CDN媒体协议。
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | VALIDATION_FAILED/BAD_REQUEST | 空批次、超过50项、字符串越界或非白名单路径;整批不返回授权 |
| 401 | UNAUTHORIZED | 会话或安装无效;无单项地址 |
| 400/403/426 | 公共头、账号限制、准入、HTTPS及JWE原错误 | 继续公共协议,不放宽认证响应校验 |
| 413 | PAYLOAD_TOO_LARGE | JWE整包超过16KiB;入口可先返回未经JWE认证的HTTP拒绝 |
| 429 | TOO_MANY_REQUESTS | 网关频率/并发限制,保留Retry-After |
| 503 | SERVICE_UNAVAILABLE | 本地存储没有OSS签名器、实例身份或供应商依赖失败;整批失败,不伪造链接或静默转发普通文件 |
条目DENIED使用原领域错误,跨账号与不存在统一NOT_FOUND;当前账号未取得普通业务角色时,非本人头像用途返回FORBIDDEN。顶层成功仅表示批次处理成功,客户端仍逐项检查transport、access与code。
接入说明¶
上传、确认和资料保存保持原协议;本次只统一媒体读取描述,不删除OSS直传、私有回源或已有API文件入口,不修改后台媒体权限或桶ACL。保存只提交媒体ID、业务path和原版本字段,不提交交付URL、签名或Token。
聚合响应含可用mediaDelivery时直接使用,不再为每张图调用本接口;CDN凭证由独立凭证接口按需签发,账号内合并并发刷新,不按图片数量签发。公开缓存有效时不为显示缓存额外刷新凭证。API例外资源继续走已声明的文件接口,不能因为CDN/OSS拒绝而自行回退。
PUBLIC按cacheKey和86400秒上限缓存,PRIVATE仅内存并按账号隔离;换号、退出、注销清理私密状态及晚到回执。OSS_SIGNED到期需联网时可按path重新授权;403最多刷新并重试一次,拒绝即停止。CDN同样最多刷新一次媒体凭证,不允许无限轮询。媒体错误不代表已提交的资料/动态保存失败,不重复业务写入。
本接口供应商故障维持整批503;原业务成功聚合响应的单项媒体故障则返回UNAVAILABLE/NONE,不撤销业务成功。匿名、管理员、普通业务错误和二进制响应不经过App聚合投影。
本轮部署、服务器回归与真实OSS/CDN公网检查见统一协议验证。Flutter已报告完成统一字段解析的源码同步;真机缓存/私密隔离/播放器Range和海外移动网络仍待客户端任务验收,不能由服务器探针结果替代。