favicon-so

该 Skill 是 favicon.so 项目的 API 参考文档，说明按域名获取网站 favicon 的接口（图片模式与 JSON 元数据模式）以及把上传图片转换成含多尺寸 ICO、PNG、apple-touch-icon 与 site.webmanifest 的 favicon 包接口，并列出路由位置、核心实现文件、参数、响应格式与技术依赖，供开发者在编写集成、修改接口或排查行为时查阅。

go7hic

热度 80.37

最近更新 2026-05-11 17:30:52

分类：开发依赖：第三方 API应用场景：API 集成 / 调试排错 / 代码生成

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add favicon-so

Metadata

name: favicon-so
description: favicon.so project API reference — covers the favicon fetch API and image-to-favicon-package convert API. Use when working on API routes, building integrations, debugging favicon fetch/convert behavior, or adding new endpoints to this project.
license: MIT
metadata: {"author":"favicon.so","version":"1.0.0"}

favicon.so API

API 1: Favicon Fetch

Fetch any website's favicon by domain.

Endpoints

Method	Path	Description
GET	`/api/favicon?url={domain}`	Fetch favicon with full options
GET	`/{domain}`	Short URL, returns favicon image directly

Parameters

Param	Type	Required	Description
`url`	string	yes	Domain or URL (e.g. `github.com`)
`raw`	string	no	Set to `"true"` for JSON metadata instead of image

Response Modes

Image mode (default): Returns binary image data with headers:

Content-Type: actual image MIME type
Cache-Control: public, max-age=604800
Access-Control-Allow-Origin: *

JSON mode (raw=true):

{
  "url": "https://github.githubassets.com/favicons/favicon.svg",
  "format": "image/svg+xml",
  "isDefault": false
}

Implementation

Source: app/api/favicon/route.ts and app/[locale]/[domain]/route.ts
Core logic: lib/fetchFavicon.ts — tries HTML parsing, /favicon.ico, Google, DuckDuckGo fallbacks
Domain validation: lib/utils.ts — normalizeDomain(), isValidDomain()
Falls back to a default SVG icon when all sources fail

API 2: Image Convert

Convert any image into a complete favicon package with all sizes.

Endpoint

Method	Path	Description
POST	`/api/convert`	Upload image, get favicon package

Request

Content-Type: multipart/form-data

Field	Type	Required	Description
`image`	File	yes	Image file (PNG, JPG, WebP, GIF, BMP, TIFF)

Also accepts raw image bytes with Content-Type: image/* or application/octet-stream.

Query Parameters

Param	Type	Default	Description
`format`	string	—	Set to `"json"` for base64 JSON output instead of ZIP

Response

ZIP mode (default): Returns application/zip containing 10 files:

favicon.ico (multi-resolution: 16, 32, 48, 64, 128)
favicon-16x16.png, favicon-32x32.png, favicon-48x48.png, favicon-64x64.png, favicon-128x128.png
apple-touch-icon.png (180×180)
android-chrome-192x192.png, android-chrome-512x512.png
site.webmanifest

JSON mode (format=json):

{
  "files": {
    "favicon-16x16.png": { "size": 1234, "base64": "iVBOR..." },
    "favicon.ico": { "size": 5678, "base64": "AAAB..." },
    ...
  }
}

Implementation

Source: app/api/convert/route.ts
Image processing: jimp (pure JS, Cloudflare Workers compatible)
ICO generation: custom multi-resolution ICO builder
ZIP packaging: jszip
CORS enabled, no auth required

Architecture Notes

All API routes are in app/api/ and skip the i18n middleware
The [locale]/[domain]/route.ts catch-all serves as a short URL for favicon fetch
Reserved paths (search, convert, api, generator, skill, mcp) are excluded from the domain catch-all
Client-side convert page (app/[locale]/convert/page.tsx) uses WASM (Photon + resvg) for browser-native processing
Server-side convert API uses jimp for Node.js/Workers compatibility