端點
傳送 GET 請求,並以網域作為路徑。回應主體就是圖片本身,因此可以直接在 <img> 標籤中使用這個網址。
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 |
可接受的輸入
您可以傳入單純的網域、子網域、完整網址或國際化網域名稱。通訊協定、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 次請求。如果您預計每天傳送數百萬次請求,請先與我們聯絡。