Cravatar 官方 API 文档

基本概念

Cravatar 初认头像服务可以像普通的图片 URL 一样请求,具体格式是:

https://cravatar.cn/avatar/HASH
https://cn.cravatar.com/avatar/HASH

其中 HASH 部分是你的电子邮箱的哈希值,此电子邮箱必须在 Cravatar.com / Cravatar.cn 上注册并绑定头像,否则会尝试返回 Gravatar 头像和 QQ 头像,如果都不存在,则返回默认头像。

电子邮箱的哈希方法

总体一共以下三步:

  1. 去除首尾两边的空格
  2. 所有字母转小写
  3. 计算 MD5 值

以下以 PHP 语言进行演示:

$email   = 'cravatar@feibisi.com';
$address = strtolower( trim( $email ) );
$hash    = md5( $address );

拼接图片请求 URL

依然以 PHP 语言进行演示:

$url = 'https://cravatar.cn/avatar/' . $hash;

指定图片格式

我们当前支持四种图片返回格式,分别是:jpg 、 jpeg 、 png 、 gif 。

你可以简单的通过向图片访问 URL 拼接文件后缀的方式来访问特定格式的图片,完整的请求 URL 类似如下:

https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c.png
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c.png

特别地:在浏览器明确表明支持 webp(Accept 中包含 image/webp) 的情况下我们会强制返回 webp 格式,此时用户无法手工指定图片格式。之所以这样设计是因为 webp 已经可以完全取代其他格式,同时其提供了更小的体积,这给予了我们更快的加载速度。

额外的参数

调整头像大小

默认情况下,我们会返回 80x80 尺寸的头像,但是你可以通过 s size 参数来指定要获取的头像大小,完整的 URL 类似如下:

https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c?s=400
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?s=400

以上 URL 将返回一个 400x400 的图像

默认头像

如果你的邮箱哈希无法匹配到任何头像,则返回我们的默认头像:

你可以通过 d default 参数自己指定默认头像:

https://cravatar.cn/avatar/245467ef31b6f0addc72b039b922a4?d=https%3A%2F%2Fcravatar.com%2Fwp-content%2Fuploads%2Fsites%2F9%2F2021%2F07%2F4.png
https://cn.cravatar.com/avatar/245467ef31b6f0addc72b039b922a4?d=https%3A%2F%2Fcravatar.com%2Fwp-content%2Fuploads%2Fsites%2F9%2F2021%2F07%2F4.png

需要注意的是,传递的默认头像地址必须经过 URL 编码,在 PHP 中你可以这样写:

urlencode( 'https://cravatar.cn/wp-content/uploads/sites/9/2021/07/4.png' );
urlencode( 'https://cn.cravatar.com/wp-content/uploads/sites/9/2021/07/4.png' );

同时默认头像需要满足以下几个条件:

  1. 必须是公开可用的 (例如,不能位于内部网、本地开发机器、或是存在防火墙等) 。
  2. 必须可以通过标准端口 80 和 443 上的 HTTP 或 HTTPS 进行访问。
  3. 必须具有可识别的图像扩展名 (jpg 、 jpeg 、 gif 、 png)
  4. 不得包含查询字符串 (如果包含,它将被忽略)

除了允许你自己指定默认头像外,我们还准备了一组内置的默认头像,只需要传入 d=默认头像 ID 即可调用:

  • 404:如果没有与电子邮件哈希关联的图像,则不加载任何图像,而是返回 HTTP 404(未找到文件) 响应
  • mp:一个简单的卡通风格的人物轮廓
  • identicon:一个几何图案 (随机生成)
  • monsterid:具有不同颜色、面孔的 「怪物」(随机生成)
  • wavatar:具有不同特征和背景的人脸 (随机生成)
  • retro:8 位色的像素人脸 (随机生成)
  • robohash:具有不同颜色、面部的机器人 (随机生成)
  • blank:透明的 PNG 图像 (为方便演示,已为其添加了一个边框)

强制加载默认头像

如果由于某种原因你想强制始终返回默认头像,您可以使用 fforcedefault 参数并将其值设置为 y

https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c?f=y
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?f=y

指定要显示的头像级别

该选项存在于 Gravatar 中,但 Cravatar 并不提供对该选项的支持。这同样是为了符合中国法律。

组合参数

以上所介绍的所有关于 Cravatar 的参数都可以自由组合,比如你可以提供这样的一个头像 URL:

https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c.png?s=200&d=retro&f=y
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c.png?s=200&d=retro&f=y

以上头像 URL 将始终返回格式为 png 、尺寸为 200 的 8 位色像素人脸。

文档最后修改于

文派文库团队编撰