---
title: 头像上传
description: 账户头像上传流程、文件限制、标准化、动画限制与审核行为。
editUrl: true
head: []
template: doc
sidebar:
  order: 2
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

## 上传流程

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

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

## 限制

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

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

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

## 动画限制

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

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

## 审核与交付状态

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

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

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

## 客户端建议

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

## 相关阅读

- [头像声明与交付](/zh-cn/user-generated-content/avatar-claims-and-delivery/) —— 应用如何收到头像 URL。
- [头像审核生命周期](/zh-cn/user-generated-content/avatar-review-lifecycle/) —— 待审核、通过和拒绝分别意味着什么。
- [身份声明与共享](/zh-cn/concepts/identity-claims/) —— 声明策略与用户同意。