跳至主要內容
Favicon.is

API 文件

Favicon.is 是一個簡單的 HTTP API,能以圖片形式回傳任何網站的圖示。不需要金鑰、不需要 SDK,也不必處理速率限制標頭。

端點

傳送 GET 請求,並以網域作為路徑。回應主體就是圖片本身,因此可以直接在 <img> 標籤中使用這個網址。

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

可接受的輸入

您可以傳入單純的網域、子網域、完整網址或國際化網域名稱。通訊協定、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 次請求。如果您預計每天傳送數百萬次請求,請先與我們聯絡。