POST/api/v1/media/uploads/{uploadId}/complete
App Bearer、八项公共头、本人上传意图;非头像须普通业务准入JSON 响应接入指南 ↗

确认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项范围见统一协议验证,不代表真机播放器验收。