跳到主要内容
Favicon.is

API 文档

Favicon.is 是一个简单的 HTTP API,能以图片形式返回任意网站的图标。无需密钥,无需 SDK,也不用处理限流响应头。

接口

发送 GET 请求,以域名作为路径。响应体就是图片本身,因此可以直接在 <img> 标签中使用该 URL。

GEThttps://favicon.is/{domain}
示例
<img src="https://favicon.is/github.com" width="32" height="32" alt="GitHub">
GitHub faviconGitHub favicon (256 px)

查询参数

参数类型默认值说明
sizeinteger128图标尺寸(像素)。可选 16、32、48、64、128 或 256;其他值会取最接近的支持尺寸。?size=64
largerbooleanfalse返回高清图标(256 px),等同于 size=256。?larger=true
originalbooleanfalse跳过 Google 网站图标缓存,读取网站自身 HTML 中声明的图标。?original=true
downloadbooleanfalse发送 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 次请求。如果你计划每天发送数百万次请求,请先与我们联系。