POST/api/v1/media/uploads
App Bearer、八项公共头;头像允许注册中账号,其他用途须普通业务准入JSON 响应接入指南 ↗

申请OSS单文件直传

请求参数

用于注册头像、资料头像/相册、动态图片/视频/语音、举报证据和明信片照片。当前仅OSS环境签发授权,本地存储环境返回503。上传原始文件后还须确认上传,确认响应才包含可绑定的业务媒体ID。上传或确认均不代替资料保存、内容审核或投递。

八项公共请求头全部必填并绑定真实Bearer会话;X-Client-Type=app,平台ios/android。头像允许注册中及VIP待准入账号,其他用途要求服务端ROLE_USER。JSON适用统一JWE,正式环境强制HTTPS。请求及授权响应均须禁止缓存,不打印签名URL或headers。无路径及查询参数。

JSON字段 类型 必填 约束
clientRequestId UUID 是 当前用户申请幂等号;相同号必须对应同一份文件声明
purpose string 是 下表枚举,不能指定桶、对象路径、用户ID或公开URL
contentType string 是 实际上传字节的MIME,严格小写,不带参数
sizeBytes integer 是 实际上传字节数,至少1字节;图片压缩后计算
contentMd5 string 是 实际上传字节MD5的标准Base64,固定24字符;非文件名或十六进制文本
durationMillis integer 否 仅VIDEO/VOICE可传,0–3600000毫秒;省略或null为未声明,不是可信媒体探测
purpose 文件上限 允许contentType 暂存对象目录 确认后的正式目录
AVATAR 10MiB image/jpeg、image/png、image/webp media/staging/avatars/ media/avatars/
ALBUM_PHOTO 10MiB 同上 media/staging/album-photos/ media/album-photos/
POST_PHOTO 20MiB 同上 media/staging/post-photos/ media/post-photos/
POSTCARD_PHOTO 5MiB 同上 media/staging/postcard-photos/ media/postcard-photos/
EVIDENCE 5MiB 同上 media/staging/report-evidence/ media/report-evidence/
VIDEO 100MiB video/mp4、video/quicktime、video/webm media/staging/videos/ media/videos/
VOICE 100MiB audio/mp4、audio/mpeg、audio/aac、audio/ogg、audio/wav、audio/x-wav、audio/webm、audio/amr media/staging/voices/ media/voices/

每个原始对象使用暂存目录/{服务端uploadId}/source;正式对象使用独立服务端媒体UUID。确认时图片仍真实解码,限制单边4096及1600万像素,移除元数据并重编码最长边1024的PNG。音视频保留原始字节;VIDEO在确认时由服务端调用OSS的0毫秒截帧,真实解码、规范化并保存PNG封面,客户端不上传首帧。OSS截帧支持H.264/H.265,不能仅按MP4/MOV/WebM后缀保证编码受支持;无法处理时确认返回400,云故障返回503。同一uploadId可重试确认,不重复PUT。本接口仍未新增可信时长/视频尺寸探测或转码。聊天图片和聊天视频尚无业务上传入口,不能借动态用途绕过聊天权限。

每用户每小时最多40个新上传意图,同时最多20个未确认意图、声明总大小最多1GiB;确认还执行原场景额度。申请幂等保留至记录清理,相同号与不同声明返回409。PUT最晚10分钟,确认24小时;已有角色临时凭证提前失效也可能使授权提前失效。相同幂等号不延长原截止时间。

请求示例

以下是JWE封装前的逻辑JSON,示例文件为4字节内容的MD5,仅演示字段,不是合法图片;正式请求按实际文件计算摘要。

curl -X POST 'https://api.budyoo.cn/api/v1/media/uploads' \
  -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 '{"clientRequestId":"11111111-1111-4111-8111-111111111111","purpose":"AVATAR","contentType":"image/png","sizeBytes":4,"contentMd5":"jXd/OF09/siBXSD3SWAm3A=="}'

成功响应

HTTP 200,公共code/message/data/errors封装;以下为解密后的逻辑结构,签名以占位符表示,不能直接调用。

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "uploadId": "22222222-2222-4222-8222-222222222222",
    "method": "PUT",
    "uploadUrl": "https://example-private-bucket.oss-cn-shenzhen.aliyuncs.com/media/staging/avatars/22222222-2222-4222-8222-222222222222/source?<短效签名>",
    "headers": {
      "Content-Type": "image/png",
      "Content-Length": "4",
      "Content-MD5": "jXd/OF09/siBXSD3SWAm3A==",
      "x-oss-forbid-overwrite": "true",
      "x-oss-server-side-encryption": "AES256"
    },
    "uploadExpiresAt": "2026-11-16T12:10:00Z",
    "completeExpiresAt": "2026-11-17T12:00:00Z"
  },
  "errors": []
}
data字段 类型 可空 含义
uploadId UUID 否 后续确认/取消唯一编号,不能用于业务保存
method string 否 固定PUT
uploadUrl string 否 原样使用的标准OSS HTTPS短效签名URL,包含敏感查询,不拼接处理参数
headers object(string→string) 否 逐项原样发送的头,键大小写不固定,值不可改动
uploadExpiresAt ISO 8601 UTC 否 本次PUT最晚有效时间;不会因重复申请延长
completeExpiresAt ISO 8601 UTC 否 后端确认截止时间

OSS PUT使用独立连接,直接发送文件字节,带全部返回头。不得附带本站Bearer、Cookie、公共头或JWE,不跟随重定向,不自动重试。V4签名绑定唯一对象、Content-Length、Content-Type、Content-MD5、禁止覆盖与SSE;URL不能用于GET、DELETE、列举或其他对象。OSS返回ETag仅为对象回执,不能授予绑定或公开权限。

失败响应

HTTP code 处理
400 INVALID_UPLOAD 用途、MIME、摘要、时长或必要声明无效
413 PAYLOAD_TOO_LARGE 超过用途字节上限
401/403 UNAUTHORIZED/FORBIDDEN/VIP_REQUIRED 登录、安装或服务端准入不满足
409 UPLOAD_CONFLICT 幂等号对应其他声明或已取消
409 UPLOAD_EXPIRED 原PUT截止时间已过,重新选择新意图号
429 AUTH_RATE_LIMITED/PHOTO_QUOTA_EXCEEDED 申请或在途额度不足
503 SERVICE_UNAVAILABLE 云签名/存储不可用;不产生假授权
{"code":"INVALID_UPLOAD","message":"上传信息或文件无效,请重新选择文件。","data":null,"errors":[]}

公共头、账号限制、HTTPS及JWE错误继续遵循公共协议。

接入说明

五个旧App multipart POST入口已从控制器移除,Nginx与Java在读取正文前返回410/UPLOAD_ENDPOINT_REMOVED;其他App API也拒绝multipart、image、audio、video及application/octet-stream文件请求类型,后台独立上传不受影响。本站直传JSON请求整包(含JWE外层)最多16KiB,超过返回413;文件本身仍按用途上限由OSS接收。旧安装包必须更新,不再提供服务器文件上传回退。Flutter应先准备实际上传文件,再计算长度和MD5、申请、直传、确认;保存只消费确认后的media。PUT超时、丢失ETag或收到409不能据此重传;使用同一uploadId并以空JSON确认,由后端读取真实对象状态。取消只影响后端确认,已签发URL到期前可能仍可PUT;清理延迟到签名失效后一小时,未确认对象24小时后回收,供应商失败持续重试。

实现位于upload/,领域导入通过公开api复用原图片规范化、归属、额度、暂存与审核。2026-11-17服务器1374项回归0失败/0错误,1项真实翻译调用条件跳过;七用途从Mac直传真实OSS,确认、重复确认、鉴权读取、音频Range、签名类型篡改及防覆盖通过。API调用经受信域名TLS的SSH转发,OSS PUT由Mac直连公网;不表示App公网域名或设备验收已完成。本轮视频首帧的专项、真实链路及清理范围见上传确认。CDN和自定义加速域名不参与本上传协议。 确认后使用回执内的统一媒体地址,或按业务path申请下载授权,由服务端选择CDN、OSS或API交付;Flutter下载适配及实际验收范围见该接口。

2026-11-20部署后,通过真实公网API/ESA、HTTPS/JWE和OSS再次验证AVATAR与VIDEO申请、直传和确认,后续CDN图片、H.264视频/首帧、Range与权限检查通过。文件PUT仍直接走OSS,确认后的读取地址由统一交付协议选择;本次没有重做其他五用途的公网直传或Flutter真机验收。完整39项检查及合成数据清理见统一协议验证。