跳转到内容
Sudomimus

头像上传

查看 Markdown

用户在 With 门户中管理自己的账户头像。如果你的界面会嵌入账户门户，或直接调用 With 账户接口，请把上传当成一次 upload intent 流程：先创建上传意图，用返回的表单字段把文件上传到对象存储，然后完成意图，让 Sudomimus 验证并处理图片。

上传流程

Section titled “上传流程”
  1. 读取 /me/avatar，展示当前头像和上传限制。
  2. 使用候选文件的 contentType 与 contentLength 创建上传意图。
  3. 用返回的 uploadUrl、method 和 fields 提交文件。
  4. 完成上传意图。
  5. 完成后重新读取 /me/avatar，展示当前预览和审核状态。

With REST client 将这些操作暴露为 getAvatar、createAvatarUploadIntent、completeAvatarUploadIntent 和 resetAvatar。

限制

Section titled “限制”

/me/avatar 会返回当前上传限制：

字段含义
maxBytes账户头像接口返回的上传字节上限。目前它与 candidateMaxBytes 相同。
candidateMaxBytes提交到对象存储的原始文件大小上限。当前为 8 MiB。
acceptedMimeTypes当前为 image/png、image/jpeg、image/webp 和 image/gif。
outputSize标准化后的正方形输出尺寸。当前为 512。

当 contentLength 为空或超过 candidateMaxBytes 时，创建意图请求会被拒绝。完成意图时，服务端还会再次验证已上传对象的真实元数据，所以客户端不要把“创建意图成功”理解成“文件必然接受”。

动画限制

Section titled “动画限制”

GIF 和 WebP 候选文件会被视为可能有动画。处理时，Sudomimus 最多接受 60 帧、总时长最多 5 秒。静态 PNG、JPEG、WebP 和 GIF 上传仍然会有一个动态 URL；如果没有动画，这个 URL 会指向静态版本。

上传头像和生成头像的公开交付都使用 WebP。处理完成后，不要依赖原始扩展名、输入 MIME type 或帧数。

审核与交付状态

Section titled “审核与交付状态”

头像响应会把当前账户头像和上传头像审核状态分开：

字段含义
avatar.url当前静态账户头像 URL。
avatar.animatedUrl当前动态账户头像 URL；没有动画时为静态 URL。
avatar.sourceGENERATED 或 UPLOAD。
avatar.hasAnimation当前账户头像是否有动态版本。
avatar.status当前账户头像的处理状态。
uploadedAvatar.reviewStatus上传头像的审核状态：PENDING、APPROVED 或 REJECTED。

新上传还在审核时，账户页可以展示上传预览；但对外应用仍会收到当前已批准头像，或者生成的兜底头像。如果审核拒绝某次上传，你的 UI 应准备好显示生成头像或上一张可用头像。交付 URL 只是展示资料，不是永久标识符。

客户端建议

Section titled “客户端建议”
  • 使用服务端返回的上传限制，不要在 UI 中硬编码。
  • 按意图响应中返回的表单字段原样上传。
  • 只有对象存储上传成功后，才完成意图。
  • 完成后重新读取 /me/avatar，让 UI 使用服务端当前 URL。
  • 只有在你的界面适合动效时才显示动态头像；否则使用静态 URL。
  • 不要保存上传原图、解析 Sudomimus 头像 URL，或把头像 URL 当作账户键。

相关阅读

Section titled “相关阅读”