# Favicon API 文档

## API 概述

该 API 服务用于获取网站的 favicon 图标。不仅限于 WordPress 站点，它会自动检测并返回目标网站的 favicon 图标。如果无法获取到目标网站的 favicon，将返回默认图标。

## API 端点

```markup
https://cn.cravatar.com/favicon/api/index.php
```

## 请求参数

<figure class="wp-block-table" id="bkmrk-%E5%8F%82%E6%95%B0%E5%90%8D%E7%B1%BB%E5%9E%8B%E5%BF%85%E5%A1%AB%E6%8F%8F%E8%BF%B0urlstring%E6%98%AF%E7%9B%AE"><table class="has-fixed-layout"><thead><tr><th>参数名</th><th>类型</th><th>必填</th><th>描述</th></tr></thead><tbody><tr><td>url</td><td>string</td><td>是</td><td>目标网站的 URL</td></tr><tr><td>refresh</td><td>boolean</td><td>否</td><td>是否强制刷新缓存</td></tr></tbody></table>

</figure>## 使用示例

<figure class="wp-block-image size-full" id="bkmrk-">![](https://cravatar.com/developer/wp-content/uploads/sites/18/2024/12/3bac151a2362067a4f21d3b95759cc2f.png)</figure>### 基础用法

```markup
https://cn.cravatar.com/favicon/api/index.php?url=cravatar.com
```

### 强制刷新缓存

```markup
https://cn.cravatar.com/favicon/api/index.php?url=cravatar.com&refresh=1
```

### 备用域名

- cn.cravatar.com （仅国内加速）
- cn.cravatar.com （国内+国际）
- en.cravatar.com （仅海外加速）

<figure class="wp-block-image size-full" id="bkmrk--2">![](https://cravatar.com/developer/wp-content/uploads/sites/18/2024/12/f53fd88f300f1139bb5e8320b7274089.png)</figure>## 响应说明

- 响应格式：图片文件（image/x-icon 或 image/svg+xml）
- 如果成功获取到 favicon，将直接返回图标文件
- 如果获取失败，将返回默认图标

## 缓存机制

- API 默认会缓存获取到的 favicon
- 使用 `refresh=1` 参数可以强制刷新缓存

## 使用示例代码

### HTML 中使用

```markup
<link rel="icon" href="https://cn.cravatar.com/favicon/api/index.php?url=cravatar.com">
```

### Markdown 中使用

```markup
![favicon](https://cn.cravatar.com/favicon/api/index.php?url=cravatar.com)
```

## 注意事项

1. 请确保提供的 URL 是有效的网址
2. API 支持 HTTP 和 HTTPS 协议的网站
3. 建议使用完整的域名，例如使用 `example.com` 而不是 `www.example.com`
4. API 有默认超时设置，如果目标网站响应较慢可能会返回默认图标

## 错误处理

- 如果提供的 URL 无效，将返回 404 状态码
- 如果无法获取目标网站的 favicon，将返回默认图标
- 如果目标网站返回非 200 状态码，将返回默认图标

## 示例响应头

成功获取并命中缓存时：

```markup
Content-Type: image/x-icon
X-Icon-Cache: Hit
```

## 使用限制

- 建议合理使用刷新缓存功能，避免频繁请求
- 请遵守合理的请求频率，避免对服务器造成过大压力

## 支持格式

- ICO
- PNG
- SVG
- JPG