favicon.so API
API 1: Favicon Fetch
Fetch any website's favicon by domain.
Endpoints
| Method | Path | Description |
|---|
| GET | INLINECODE0 | Fetch favicon with full options |
| GET |
/{domain} | Short URL, returns favicon image directly |
Parameters
| Param | Type | Required | Description |
|---|
| INLINECODE2 | string | yes | Domain or URL (e.g. github.com) |
| INLINECODE4 |
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 - INLINECODE7
- INLINECODE8
JSON mode (raw=true):
CODEBLOCK0
Implementation
- - Source:
app/api/favicon/route.ts and INLINECODE11 - Core logic:
lib/fetchFavicon.ts — tries HTML parsing, /favicon.ico, Google, DuckDuckGo fallbacks - Domain validation:
lib/utils.ts — normalizeDomain(), INLINECODE16 - 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 | INLINECODE17 | Upload image, get favicon package |
Request
Content-Type: multipart/form-data
| Field | Type | Required | Description |
|---|
| INLINECODE19 | 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 |
|---|
| INLINECODE22 | 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) - INLINECODE26 ,
favicon-32x32.png, favicon-48x48.png, favicon-64x64.png, INLINECODE30 - INLINECODE31 (180×180)
- INLINECODE32 , INLINECODE33
- INLINECODE34
JSON mode (format=json):
CODEBLOCK1
Implementation
- - Source: INLINECODE36
- Image processing:
jimp (pure JS, Cloudflare Workers compatible) - ICO generation: custom multi-resolution ICO builder
- ZIP packaging: INLINECODE38
- 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
favicon.so API
API 1：Favicon 获取
通过域名获取任意网站的 favicon。
端点
| 方法 | 路径 | 描述 |
|---|
| GET | /api/favicon?url={domain} | 使用完整选项获取 favicon |
| GET |
/{domain} | 短链接，直接返回 favicon 图片 |
参数
| 参数 | 类型 | 必填 | 描述 |
|---|
| url | 字符串 | 是 | 域名或 URL（例如 github.com） |
| raw |
字符串 | 否 | 设置为 true 以返回 JSON 元数据而非图片 |
响应模式
图片模式（默认）：
返回二进制图片数据，包含以下头部：
- - Content-Type：实际图片 MIME 类型
- Cache-Control: public, max-age=604800
- Access-Control-Allow-Origin: *
JSON 模式（raw=true）：
json
{
url: https://github.githubassets.com/favicons/favicon.svg,
format: image/svg+xml,
isDefault: false
}
实现
- - 源码：app/api/favicon/route.ts 和 app/[locale]/[domain]/route.ts
- 核心逻辑：lib/fetchFavicon.ts — 尝试 HTML 解析、/favicon.ico、Google、DuckDuckGo 回退
- 域名验证：lib/utils.ts — normalizeDomain()、isValidDomain()
- 当所有来源均失败时，回退到默认 SVG 图标
API 2：图片转换
将任意图片转换为包含所有尺寸的完整 favicon 包。
端点
| 方法 | 路径 | 描述 |
|---|
| POST | /api/convert | 上传图片，获取 favicon 包 |
请求
Content-Type： multipart/form-data
| 字段 | 类型 | 必填 | 描述 |
|---|
| image | 文件 | 是 | 图片文件（PNG、JPG、WebP、GIF、BMP、TIFF） |
也接受原始图片字节，Content-Type 为 image/* 或 application/octet-stream。
查询参数
| 参数 | 类型 | 默认值 | 描述 |
|---|
| format | 字符串 | — | 设置为 json 以返回 base64 JSON 输出而非 ZIP |
响应
ZIP 模式（默认）：
返回 application/zip，包含 10 个文件：
- - favicon.ico（多分辨率：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 模式（format=json）：
json
{
files: {
favicon-16x16.png: { size: 1234, base64: iVBOR... },
favicon.ico: { size: 5678, base64: AAAB... },
...
}
}
实现
- - 源码：app/api/convert/route.ts
- 图片处理：jimp（纯 JS，兼容 Cloudflare Workers）
- ICO 生成：自定义多分辨率 ICO 构建器
- ZIP 打包：jszip
- 启用 CORS，无需认证
架构说明
- - 所有 API 路由位于 app/api/ 下，跳过 i18n 中间件
- [locale]/[domain]/route.ts 通配路由作为 favicon 获取的短链接
- 保留路径（search、convert、api、generator、skill、mcp）被排除在域名通配路由之外
- 客户端转换页面（app/[locale]/convert/page.tsx）使用 WASM（Photon + resvg）进行浏览器原生处理
- 服务端转换 API 使用 jimp 以实现 Node.js/Workers 兼容性
