# Cravatar 官方 API 文档
# 基本概念
Cravatar 初认头像服务可以像普通的图片 URL 一样请求，具体格式是：
```
https://cn.cravatar.com/avatar/HASH
```
```
https://cn.cravatar.com/avatar/HASH
```
其中 HASH 部分是你的电子邮箱的哈希值，此电子邮箱必须在 [Cravatar.com](https://cravatar.com/) / [cn.cravatar.com](https://cn.cravatar.com) 上注册并绑定头像，否则会尝试返回 Gravatar 头像和 QQ 头像，如果都不存在，则返回默认头像。
## 电子邮箱的哈希方法
总体一共以下三步：
1. 去除首尾两边的空格
2. 所有字母转小写
3. 计算 MD5 值
以下以 PHP 语言进行演示：
```
$email = 'cravatar@feibisi.com';
$address = strtolower( trim( $email ) );
$hash = md5( $address );
```
## 拼接图片请求 URL
依然以 PHP 语言进行演示：
```
$url = 'https://cn.cravatar.com/avatar/' . $hash;
```
## 指定图片格式
我们当前支持四种图片返回格式，分别是：jpg、jpeg、png、gif。
你可以简单的通过向图片访问 URL 拼接文件后缀的方式来访问特定格式的图片，完整的请求 URL 类似如下：
```
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c.png
```
```
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c.png
```
> 特别地：在浏览器明确表明支持 webp（Accept 中包含 `image/webp`）的情况下我们会强制返回 webp 格式，此时用户无法手工指定图片格式。之所以这样设计是因为 webp 已经可以完全取代其他格式，同时其提供了更小的体积，这给予了我们更快的加载速度。
## 额外的参数
### 调整头像大小
默认情况下，我们会返回 80×80 尺寸的头像，但是你可以通过` s `或 `size `参数来指定要获取的头像大小，完整的 URL 类似如下：
```
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?s=400
```
```
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?s=400
```
以上 URL 将返回一个 400×400 的图像
### 默认头像
如果你的邮箱哈希无法匹配到任何头像，则返回我们的默认头像：
你可以通过 d 或 default 参数自己指定默认头像：
```
https://cn.cravatar.com/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.com/wp-content/uploads/sites/9/2021/07/4.png' );
```
```
urlencode( 'https://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 图像（为方便演示，已为其添加了一个边框）
- 
- 
- 
- 
- 
- 
- 
### 强制加载默认头像
如果由于某种原因你想强制始终返回默认头像，您可以使用 `f` 或 `forcedefault` 参数并将其值设置为 `y`。
```
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?f=y
```
```
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?f=y
```
### 指定要显示的头像级别
该选项存在于 Gravatar 中，但 Cravatar 并不提供对该选项的支持。这同样是为了符合中国法律。
### 组合参数
以上所介绍的所有关于 Cravatar 的参数都可以自由组合，比如你可以提供这样的一个头像URL：
```
https://cn.cravatar.com/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 位色像素人脸。