接口
发送 GET 请求,以域名作为路径。响应体就是图片本身,因此可以直接在 <img> 标签中使用该 URL。
GET
https://favicon.is/{domain}示例
<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">查询参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| size | integer | 128 | 图标尺寸(像素)。可选 16、32、48、64、128 或 256;其他值会取最接近的支持尺寸。?size=64 |
| larger | boolean | false | 返回高清图标(256 px),等同于 size=256。?larger=true |
| original | boolean | false | 跳过 Google 网站图标缓存,读取网站自身 HTML 中声明的图标。?original=true |
| download | boolean | false | 发送 Content-Disposition 响应头,让浏览器将图标作为文件下载。?download=1 |
支持的输入
你可以传入纯域名、子域名、完整 URL 或国际化域名。协议、www.、端口、路径和查询字符串会被自动去除,域名匹配不区分大小写。
示例
https://favicon.is/github.com
https://favicon.is/docs.github.com
https://favicon.is/https://github.com/features/actions
https://favicon.is/WWW.GitHub.com:443
https://favicon.is/bücher.de
https://favicon.is/例子.中国基于 IANA 顶级域名的域名校验
Favicon.is 只会为后缀属于 IANA 根区数据库中已委派顶级域名的域名获取图标。对于其他后缀(例如 .local、.test 或拼写错误)的请求,会立即返回默认图标,不会联系任何服务器。
查看所有支持的顶级域名响应
请求成功时返回 HTTP 200 和图片(通常为 PNG,有时为 ICO 或 SVG)。即使找不到图标,也同样会返回 HTTP 200 和默认图标,因此你的页面永远不会出现破损图片。
cURL
$ curl -I https://favicon.is/github.com
HTTP/2 200
content-type: image/png
cache-control: public, max-age=86400, stale-while-revalidate=604800
access-control-allow-origin: *
etag: "8c1f3b6a2d4e5f60718293a4"
x-source: cache-r2
x-response-time: 3ms响应头
- Content-Type
- 图片格式:image/png、image/x-icon、image/svg+xml、image/jpeg、image/gif 或 image/webp。
- Cache-Control
- 图标可被浏览器和 CDN 缓存一天,并在一周内于后台重新验证。
- X-Source
- 图标来源:cache-edge、cache-r2、google、live 或 default。
- X-Reason
- 仅在返回默认图标时出现,用于说明原因:invalid-domain、unsupported-tld、not-found 或 failure-cache。
- X-Response-Time
- 请求在我们服务端的处理耗时。
- Access-Control-Allow-Origin
- Access-Control-Allow-Origin: * 让你可以在 canvas 上绘制图标,或从任意来源获取图标。
缓存与更新
每个图标都会存储在 Cloudflare R2 中,并缓存在提供服务的数据中心的边缘缓存里。重复请求通常只需几毫秒。
已存储的图标会在七天后于后台刷新,因此网站更换 Logo 后会自动更新,且不会拖慢任何人的访问速度。
如果某个网站完全没有图标,该结果会被记住一小时,以免重复查询对其造成压力。
默认图标
当没有可用图标时,API 会返回这个中性的占位图标。如需识别这种情况,可检查 X-Source 响应头的值是否为 default。
cURL
$ curl -I https://favicon.is/example.invalid
HTTP/2 200
content-type: image/svg+xml
x-source: default
x-reason: unsupported-tld检测 API(JSON)
网站图标检测工具基于一个 JSON 接口,它会列出网站声明的所有图标:link 标签、Web 应用清单和 /favicon.ico,并包含实际像素尺寸。
JSON
GET https://favicon.is/api/inspect?domain=github.com
{
"domain": "github.com",
"url": "https://github.com/",
"title": "GitHub · Build and ship software on a single, collaborative platform",
"reachable": true,
"icons": [
{
"href": "https://github.githubassets.com/favicons/favicon.svg",
"rel": "icon",
"type": "image/svg+xml",
"source": "link",
"ok": true,
"contentType": "image/svg+xml",
"width": 32,
"height": 32
}
],
"manifest": { "href": "https://github.com/manifest.json", "ok": true, "icons": [ … ] },
"checks": { "ico": true, "svg": true, "appleTouch": true, "manifest": true, "large": true }
}合理使用
图片接口免费,正常使用没有硬性限制。检测 API 限制为每个 IP 地址每分钟 30 次请求。如果你计划每天发送数百万次请求,请先与我们联系。