申请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项检查及合成数据清理见统一协议验证。