快速开始

最简单的使用方式，直接在 HTML 中引用头像地址。

avatar.wifilu.com — html 
<img src="https://cdn.wifilu.com/avatar/b2518593dfbc67ba8bc8e39bb30541fa3d8a7002f87240f2f8a6b99f26e4c9eb" alt="头像">

访问指定的 hash 地址即可获取对应的头像，如果 hash 不存在，系统会自动随机选择一张头像并建立映射关系。

以上头像由 API 实时返回

在 WPOPT 插件中引用

如果你使用 WordPress，可以通过 WPOPT 插件轻松替换 Gravatar 头像。

  1. 安装并启用 WPOPT 插件
  2. 进入 WPOPT 设置 → 优化加速 → 头像服务器
  3. 选择"自定义"
  4. 填入自定义头像地址：cdn.wifilu.com/avatar
  5. 保存设置即可生效
提示：WPOPT 插件会自动处理所有 Gravatar 头像请求，无需修改主题代码。
WPOPT 插件设置截图

WPOPT 插件 头像服务器设置界面

API 参数

参数 类型 必填 默认值 说明
hash string 是 - 32位 MD5 或 64位 SHA-256 哈希值
s integer 否 96 图片尺寸（像素）
d string 否 - 默认头像类型（兼容 Gravatar）
r string 否 g 内容评级：g, pg, r, x
f string 否 - 强制使用默认头像
y string 否 - 强制刷新缓存

使用示例

基本使用

avatar — basic 
GET https://cdn.wifilu.com/avatar/b2518593dfbc67ba8bc8e39bb30541fa3d8a7002f87240f2f8a6b99f26e4c9eb

返回 PNG 格式的头像图片，默认尺寸 96x96 像素。

指定尺寸

avatar — size 
GET https://cdn.wifilu.com/avatar/b2518593dfbc67ba8bc8e39bb30541fa3d8a7002f87240f2f8a6b99f26e4c9eb?s=200

返回 200x200 像素的头像图片。

完整参数示例

avatar — full params 
GET https://cdn.wifilu.com/avatar/b2518593dfbc67ba8bc8e39bb30541fa3d8a7002f87240f2f8a6b99f26e4c9eb?s=96&d=mm&r=g

返回 96x96 像素的头像，使用 mm 默认头像，内容评级为 g。

响应状态码

状态码 说明
200 OK 请求成功，返回头像图片
304 Not Modified 缓存未过期，使用本地缓存
404 Not Found 请求的资源不存在（当 d=404 时）

映射机制

本服务使用哈希映射机制来管理头像。

  1. 自动映射：首次访问某个哈希时，系统自动随机分配一个头像
  2. 持久化存储：哈希与头像的映射关系会被保存
  3. 映射有效期：映射关系保存 30 天
  4. 固定返回：在有效期内，相同哈希始终返回同一头像
提示：如果请求的 hash 不存在，系统会自动随机选择一张头像并建立映射关系。映射关系会保存 30 天，期间相同 hash 将始终返回固定头像。

哈希格式

本服务支持两种哈希格式。

MD5 哈希

32 位十六进制字符串
示例：e64c7d89f26bd1972efa854d13d7dd61

SHA-256 哈希

64 位十六进制字符串
示例：a26cb3b21a52d46007baee28bade0c845292e09e268bae7414f34a04502cc859

注意：哈希值只能包含小写字母 a-f 和数字 0-9，长度必须为 32 或 64 位。