确认OSS上传并取得媒体回执¶
请求参数¶
用于直传后的服务端确认。八项公共请求头全部必填,当前Bearer及安装须匹配本人意图;头像允许注册中账号,其他用途要求普通业务权限。JSON按统一JWE处理,正式环境HTTPS,响应no-store。无查询参数。
| 字段 | 位置/类型 | 必填 | 约束 |
|---|---|---|---|
| uploadId | path UUID | 是 | 本人申请时的服务端编号 |
| etag | JSON string | 否 | PUT回执ETag,允许HTTP双引号;最多128字符、内部限字母数字和短横线。省略或null时由后端核对真实对象 |
JSON体必须存在;无ETag用{}。ETag只是额外一致性条件,客户端不提交用户、Key、大小、类型或媒体ID。服务器始终重新HEAD核对固定Key的类型与长度,并经内网完整读回计算MD5,再执行既有领域规范化及额度检查。非本人和不存在统一404。
同一uploadId的成功确认幂等;意图锁、账号锁及原媒体记录与回执同事务提交,重复/并发确认只生成一个媒体ID。响应丢失可重试同一确认。确认截止后拒绝首次确认;已经成功的回执在意图保留期间仍可重读。回执至少保留暂存清理后7天,业务媒体是否仍有效由后续保存/读取接口判断。
请求示例¶
以下为JWE前的逻辑JSON。
curl -X POST 'https://api.budyoo.cn/api/v1/media/uploads/22222222-2222-4222-8222-222222222222/complete' \
-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 '{}'
成功响应¶
以下成功示例按2026-11-20已部署的统一协议展示;CDN示例为合成对象,默认头像示例使用API通道,真实地址及权限以服务端返回为准。
HTTP 200。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"uploadId": "22222222-2222-4222-8222-222222222222",
"purpose": "AVATAR",
"media": {
"avatarId": "33333333-3333-4333-8333-333333333333",
"contentType": "image/png",
"sizeBytes": 125,
"contentPath": "https://media.budyoo.cn/media/avatars/33333333-3333-4333-8333-333333333333.png",
"avatarUrl": "https://media.budyoo.cn/media/avatars/33333333-3333-4333-8333-333333333333.png"
}
},
"errors": [],
"mediaDelivery": [
{
"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:a1820b3bac8ee872f72c82bf5f60ac23405db096d6f3e5f877be2adedd0b4d0e",
"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"
}
}
]
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| uploadId | UUID | 否 | 原意图号,不能替代业务媒体ID |
| purpose | string | 否 | 原申请用途 |
| media | object | 否 | 下表原上传接口的data结构;媒体地址与顶层mediaDelivery按统一协议返回,通道由服务端选择 |
| purpose | media字段来源 |
|---|---|
| AVATAR | avatarId、contentType、sizeBytes、contentPath;统一投影补充avatarUrl |
| ALBUM_PHOTO | id、contentType、sizeBytes;读取路径为/api/v1/media/album-photos/{id} |
| POST_PHOTO | id、url、contentType、sizeBytes |
| POSTCARD_PHOTO | id、url、sizeBytes、stagedExpiresAt |
| VIDEO/VOICE/EVIDENCE | id、kind、url、posterUrl、contentType、sizeBytes、durationMillis、width、height、stagedExpiresAt |
| media字段 | 类型 | 返回范围/空值 | 含义 |
|---|---|---|---|
| avatarId | UUID | AVATAR,非空 | 规范化头像编号,供注册草稿或资料保存绑定 |
| id | UUID | 其余六种用途,非空 | 对应领域专用媒体编号,不能跨用途引用 |
| contentPath/avatarUrl | string或null | AVATAR | 本人头像交付URL;业务path保留在mediaDelivery,单项媒体故障为null,不影响已完成确认 |
| url | string或null | 除AVATAR/ALBUM_PHOTO外 | 统一媒体交付后的URL;原业务path在mediaDelivery中,媒体不可用为null |
| contentType | string | 除POSTCARD_PHOTO外,非空 | 图片固定image/png;原始音视频为已签名并验证的声明MIME |
| sizeBytes | integer | 全部,非空 | 处理后真实字节数;图片可能与原文件不同 |
| kind | string | VIDEO/VOICE/EVIDENCE,非空 | 与申请purpose一致的固定用途 |
| posterUrl | string或null | VIDEO/VOICE/EVIDENCE | OSS新上传VIDEO确认成功后返回已保存PNG封面地址;VOICE/EVIDENCE、旧视频或本地无截帧模式为null |
| durationMillis | integer | VIDEO/VOICE/EVIDENCE | 音视频声明毫秒数,未传或证据为0,不是可信时长探测 |
| width/height | integer | VIDEO/VOICE/EVIDENCE | 证据为规范化后真实像素;原始音视频当前为0 |
| stagedExpiresAt | ISO 8601 UTC | POSTCARD_PHOTO及VIDEO/VOICE/EVIDENCE | 首次确认生成的24小时暂存期限;重读幂等回执不刷新期限或声明当前绑定状态 |
未列入某用途的字段省略。media.sizeBytes为处理后真实字节数,图片仍固定PNG。音视频宽高0仍表示没有可信视频尺寸探测,durationMillis为声明值。OSS视频确认会先保存正式原视频,再调用OSS获取0毫秒画面,按既有图片规则真实解码(单边≤4096、≤1600万像素)、去元数据并输出最长边1024的PNG,与媒体记录和回执同事务完成;失败回滚本次已创建对象,成功幂等回执不再次截帧。封面读取复用原视频的审核/归属/屏蔽权限,暂存不公开。无法截帧或图片不合法返回400 INVALID_COMMUNITY_MEDIA,云权限/超时等故障返回503 SERVICE_UNAVAILABLE,重试原确认即可。存量视频不自动补帧,本地模式不伪造封面。五个旧App multipart上传入口已移除,不再供此回执生成或回退使用。请求整包(含JWE)上限16KiB,文件字节只传OSS。
失败响应¶
| HTTP | code | 处理 |
|---|---|---|
| 400 | INVALID_UPLOAD | ETag或对象长度/类型/完整摘要不匹配;不导入业务媒体 |
| 400 | INVALID_AVATAR/INVALID_PHOTO/INVALID_COMMUNITY_MEDIA | 图片真实解码或既有场景校验失败 |
| 401/403 | UNAUTHORIZED/FORBIDDEN/VIP_REQUIRED | 登录、安装或准入失效,不切换到新账号继续确认 |
| 404 | NOT_FOUND | 不存在或非本人 |
| 409 | UPLOAD_NOT_READY | OSS尚无对象;稍后重试同一确认,不自动重新PUT |
| 409 | UPLOAD_CONFLICT | 已取消或ETag与实际对象不同 |
| 409 | UPLOAD_EXPIRED | 首次确认超过24小时,重新开始上传 |
| 429 | AUTH_RATE_LIMITED/PHOTO_QUOTA_EXCEEDED | 原场景额度不足 |
| 503 | SERVICE_UNAVAILABLE | OSS/数据库依赖故障,不能当成对象未写入 |
{"code":"UPLOAD_NOT_READY","message":"文件尚未到达,请稍后继续确认同一次上传。","data":null,"errors":[]}
接入说明¶
2026-11-20统一媒体交付已部署到唯一正式环境(运行配置仍为dev):已认证App成功响应自动替换受支持用户媒体URL并按需附加顶层mediaDelivery,不再要求能力头;无头、cdn-v1和oss-v1均使用同一结构。服务端选择CDN/OSS/API,客户端按transport加载;原ID、版本、权限、JWE与JSON的no-store保持。非空avatarId及albumPhotoIds按统一规则补充avatarUrl/albumPhotos,单项媒体依赖失败不推翻已提交业务。完整字段、缓存与Flutter验收见统一媒体交付。
只把media交给现有模型解析及保存;上传ID、OSS ETag和短效URL都不能用于资料绑定。 显示媒体时直接把返回URL与顶层mediaDelivery交给公共加载组件,不因确认成功额外申请每张图的下载地址;仅无现成地址或签名到期时才按业务path调用下载授权。地址只用于加载,不写入资料保存字段。换号或原Model销毁后丢弃晚到回执,禁止更新其他账号界面。客户端恢复确认和取消应保留原账号作用域。
确认后业务媒体沿用原鉴权相对路径、审核与删除队列;原始暂存文件由上传维护任务回收,正式媒体不会被暂存任务删除。2026-11-17服务器全量回归及两组修正模拟后的定向复跑汇总1374项,0失败/0错误、1项真实翻译条件跳过;新增首帧专项10项覆盖固定SDK参数、有界读取、错误、归属、成功幂等、失败回滚重试、列表/主页、审核/屏蔽及删除。真实30fps H.264视频从Mac直传OSS,确认生成并保存起始画面PNG;重复确认、本人待审列表/主页、原路径下载授权、私有拒绝与注销回收共11项检查通过,合成账号及视频/封面/暂存键均已清理。本轮API经保留CA与主机名校验的域名TLS SSH转发,OSS文件由Mac直连;未对运行内容执行公开批准,不代表App公网域名或设备验收完成。旧七用途上传回归保持,首帧未逐个发现/关注等列表重复使用真实视频验收,各入口共用原Post投影。
2026-11-20统一协议已部署,真实公网确认响应在无能力头时直接返回头像、H.264视频和首帧CDN地址及mediaDelivery;视频重复确认保持相同ID和封面。本人待审动态可读取,跨账号、删除后旧地址及退出后凭证被拒绝,实际MP4三段Range与原始字节一致。合成账号和正式媒体已清理,原始暂存按签名宽限回收;完整39项范围见统一协议验证,不代表真机播放器验收。