POST/api/v1/media/downloads
App Bearer、八项公共头及JWE;本人上传头像允许注册中账号,其余媒体须普通业务准入JSON 响应接入指南 ↗

批量获取媒体交付信息

请求参数

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和海外移动网络仍待客户端任务验收,不能由服务器探针结果替代。