免费 Favicon API

一个 GET 请求,按网址获取任意网站的 favicon。无需 API key,无需注册。

快速开始

favicondl 的 favicon API 只需一个 GET 请求,就能把任意域名或网址转换成它的 favicon。不需要 API key,不需要账号,也不需要 SDK。传入 size(只接受 16、32、48、64、128、180、192、256、512;其他数字会就近归并,距离相同取更小的)会得到该边长的正方形 PNG:

<img src="https://favicondl.com/api/extract?url=github.com&size=32" width="32" height="32" alt="GitHub 的 favicon">

省略 size 则返回原始文件。比请求更小的位图会被放大,可能发虚。SVG 会按请求尺寸栅格化。图片响应上的 X-Favicon-Native-Size 和 X-Favicon-Upscaled 会说明是否放大过。

也可以请求 JSON,查看找到了哪个文件、来自哪里:

curl "https://favicondl.com/api/extract?url=github.com&format=json"
curl "https://favicondl.com/api/extract?url=github.com&size=32&format=json"
{
  "ok": true,
  "domain": "github.com",
  "size": null,
  "resized": false,
  "upscaled": false,
  "vector": true,
  "nativeWidth": null,
  "nativeHeight": null,
  "iconUrl": "https://github.githubassets.com/favicons/favicon.svg",
  "proxyUrl": "https://favicondl.com/api/proxy?url=https%3A%2F%2Fgithub.githubassets.com%2Ffavicons%2Ffavicon.svg",
  "source": "html",
  "rel": "icon",
  "format": "svg",
  "width": null,
  "height": null,
  "pageUrl": "https://github.com/",
  "candidates": [
    { "url": "https://github.githubassets.com/favicons/favicon.svg", "format": "svg", "vector": true, "source": "html", "rel": "icon", "proxyUrl": "…" },
    { "url": "https://github.githubassets.com/assets/app-icon-512-7f9c4ff2e960.png", "format": "png", "width": 512, "height": 512, "source": "manifest", "rel": "manifest", "proxyUrl": "…" },
    { "url": "https://github.com/favicon.ico", "format": "ico", "width": 32, "height": 32, "source": "direct", "rel": "favicon.ico", "proxyUrl": "…" }
  ]
}

iconUrl 是网站上的原始文件。proxyUrl 才是要下载的图片:省略 size 时是原始文件,设置了 size(例如 &size=32)时是恰好该尺寸的正方形 PNG。响应带有 Access-Control-Allow-Origin: *。

width 和 height 是实测的源图(SVG 为 null)。设置了 size 时,outputWidth 与 outputHeight 等于该值,nativeWidth / nativeHeight 是源图像素,只有位图被放大时 upscaled 才为 true,这时 PNG 可能发虚。candidates 最多列出 8 个其他已验证图标。退回到 Google 或 DuckDuckGo 时列表为空。

API 如何选出图标

  1. 首页会像普通浏览器一样被请求,并跟随重定向(包括 www ↔ 裸域名)。页面里所有图标相关的 <link> 都会被读取:icon、shortcut icon、apple-touch-icon、apple-touch-icon-precomposed 和 mask-icon。相对链接和协议相对链接(//cdn…)会按最终页面地址或页面的 <base> 标签解析(source: "html")。
  2. Web App Manifest:打开页面引用的 manifest,读取其中的图标列表,192px 和 512px 的图标通常就在这里(source: "manifest")。
  3. 常见路径 /favicon.ico 和 /apple-touch-icon.png 也会尝试(source: "direct")。
  4. 每个候选都会被下载并检查:内容必须真的是图片(PNG、ICO、SVG、WebP、JPEG、GIF 等),并且会测量它的真实像素尺寸,而不是相信文件名。
  5. Google 的 favicon 服务,其次是 DuckDuckGo,只有在网站本身的图标都不可用时才会使用,并按你请求的 size 获取(source: "google_s2" 或 "duckduckgo")。

通过验证的候选会按清晰度排序:全彩 SVG 优先,其次是尺寸最大的正方形 PNG/ICO/WebP。Safari 的单色 mask-icon 和只标注为 maskable 的 manifest 图标排位较低,因为它们看起来和普通的 favicon 不一样。选出的源图会再缩放到 16、32、48、64、128、180、192、256 或 512 之一(其他数字就近归并)。省略 size 则保留原始文件。缩小用 Lanczos,放大用高质量重采样,非正方形用透明边补齐,SVG 按请求尺寸栅格化。放大后的位图可能发虚,响应里不会把它说成清晰的原图。

如果拿到的是 google_s2,说明这个网站要么没有我们能访问到的图标,要么拦截了我们的请求(比如返回了人机验证页面)。如果只查一个网站,首页上的 favicon 下载器还会直接从你的浏览器尝试几个额外来源,并列出找到的所有尺寸供你选择。

Favicon API 对比:favicondl、Google S2、DuckDuckGo 与 Icon Horse

这四个服务都可以免费开始用,也都不需要 API key。区别在于它们返回的内容:

favicondlGoogle S2DuckDuckGoIcon Horse
接口地址/api/extract?url=example.comgoogle.com/s2/favicons?domain=example.com&sz=64icons.duckduckgo.com/ip3/example.com.icoicon.horse/icon/example.com
API key不需要不需要不需要不需要(免费套餐)
公开的免费额度无(合理使用)未公开未公开免费套餐每月 1,000 个图标
尺寸参数size 为 16、32、48、64、128、180、192、256 或 512。其他数字就近归并。省略则返回原始文件。sz无文档未说明
返回内容设置 size 时为恰好该尺寸的正方形 PNG;否则为原始文件(SVG、PNG、ICO 等)PNG 或 JPEG(实测)ICO(实测)PNG(实测)
JSON 元数据有(format=json:图标地址、来源、格式、实测像素尺寸,以及最多 8 个备选图标)无无无
我们测试 github.com 的结果favicon.svg(矢量图)sz=16 时为 16×16 PNG,sz=256 时为 180×180含 16×16 和 32×32 的 ICO256×256 PNG

以上结果来自我们在 2026 年 10 月 12 日的实际请求;Icon Horse 的额度取自其价格说明。第三方服务随时可能变化,在生产环境中依赖它们之前,请先查看各服务商的条款。

概述

Mzu favicondl 提供可直接复制的 favicon URL 模板与图标提取页面。自有的提取接口会找出网站实际提供的图标,并通过图片代理支持在浏览器里直接下载。

快速响应

平均响应时间小于100ms

免费使用

完全免费,无需注册

稳定可靠

99.9% 可用性保障

认证

本项目使用免费的 Favicon 服务 URL 模板,不需要任何认证或 API Key。

注意: 虽然我们不需要API Key,但请合理使用服务,避免过度请求。

接口端点

GET FaviconDL Extract API

查找并下载指定域名或网址的可用 favicon

基础URL:

https://favicondl.com/api/extract

完整示例:

https://favicondl.com/api/extract?url=example.com&size=128

参数说明

参数名 类型 必需 默认值 描述
url string 是 - 目标域名或网址,如:example.com
size number 否 无(原始文件) 只接受 16、32、48、64、128、180、192、256、512。其他数字会就近归到允许的尺寸(距离相同取更小的),并重定向到该地址。省略 size 则返回原始文件。不是数字则返回 400。更小的位图会被放大,可能发虚;SVG 按归并后的尺寸栅格化。
format string 否 redirect 使用 json 获取元数据;省略时直接跳转到可下载图片

参数详情:

网址

支持域名和完整网址:

  • • example.com
  • • www.example.com
  • • https://example.com/docs
  • • sub.example.com
尺寸

下面列出的尺寸之一,返回正方形 PNG。其他数字会就近归并。省略则返回原始文件。

  • • 16 - 16x16
  • • 32 - 32x32
  • • 48 - 48x48
  • • 64 - 64x64
  • • 128 - 128x128
  • • 180 - 180x180
  • • 192 - 192x192
  • • 256 - 256x256
  • • 512 - 512x512

只会读取 url(domain 仍可作为别名)、size 和 format。其他查询参数会被忽略。主机会转成小写,默认使用 https,去掉开头的一个 www.,并去掉末尾的斜杠。还不是这个形式的请求会用 308 重定向到稳定地址,CDN 缓存的就是这个地址。/api/proxy 会保留 www 和图片路径,因为它们用来定位文件。

响应格式

成功响应 (JSON格式)

JSON响应
{
  "ok": true,
  "domain": "example.com",
  "size": 32,
  "resized": true,
  "outputFormat": "png",
  "outputWidth": 32,
  "outputHeight": 32,
  "upscaled": false,
  "nativeWidth": null,
  "nativeHeight": null,
  "vector": true,
  "iconUrl": "https://example.com/favicon.svg",
  "proxyUrl": "https://favicondl.com/api/proxy?url=...&size=32",
  "source": "html",
  "rel": "icon",
  "format": "svg",
  "width": null,
  "height": null,
  "pageUrl": "https://example.com/",
  "candidates": [ ... ]
}

错误响应

错误响应
{
  "ok": false,
  "error": "Missing url"
}

注意: 当使用 format=redirect 时,API会直接重定向到图标URL,不返回JSON响应。

使用示例

JavaScript (Fetch)

JavaScript
async function getFavicon(url, size = 128) {
  const endpoint = new URL('https://favicondl.com/api/extract');
  endpoint.searchParams.set('url', url);
  endpoint.searchParams.set('size', String(size));
  const response = await fetch(endpoint);
  if (!response.ok) throw new Error(`Favicon request failed: ${response.status}`);
  return await response.blob();
}

const icon = await getFavicon('example.com', 128);
const imageUrl = URL.createObjectURL(icon);
document.querySelector('#favicon-preview').src = imageUrl;

Python (Requests)

Python
import requests

def get_favicon(url: str, size: int = 128) -> bytes:
    response = requests.get(
        "https://favicondl.com/api/extract",
        params={"url": url, "size": size},
        timeout=15,
    )
    response.raise_for_status()
    return response.content

icon_bytes = get_favicon("example.com", 128)
with open("example-favicon", "wb") as output:
    output.write(icon_bytes)

PHP (cURL)

PHP
<?php
function getFavicon(string $url, int $size = 128): string {
    $endpoint = 'https://favicondl.com/api/extract?url=' . urlencode($url) . '&size=' . $size;
    $context = stream_context_create(['http' => ['follow_location' => 1, 'timeout' => 15]]);
    $icon = file_get_contents($endpoint, false, $context);
    if ($icon === false) {
        throw new RuntimeException('Favicon request failed');
    }
    return $icon;
}

file_put_contents('example-favicon', getFavicon('example.com', 128));
?>

HTML 直接引用

HTML
<!-- Exact 32×32 PNG. Allowed: 16, 32, 48, 64, 128, 180, 192, 256, 512. Other numbers snap to the nearest. -->
<img src="https://favicondl.com/api/extract?url=example.com&size=32" alt="example.com favicon" width="32" height="32">

<!-- Omit size for the original file. Small rasters requested above native size may look soft. -->
<img src="https://favicondl.com/api/extract?url=example.com" alt="example.com favicon">

错误处理

出错时会返回 HTTP 状态码和一段简短的 JSON,其中 ok 为 false,并附带错误信息。

HTTP状态码 错误信息 描述 解决方法
400 Missing url 未传入 url 或 domain 参数 在请求中加上 ?url=example.com
400 Invalid format format 既不是 json 也不是 redirect 使用 format=json,或省略该参数以获得重定向
400 Invalid domain 无法将该值解析为主机名 传入 example.com 这样的域名或完整的 https:// 网址
405 Method not allowed 仅支持 GET 请求 改用 GET 请求
502 Favicon extraction failed 提取器未能返回图标 稍后重试
415 Target is not an image 仅 /api/proxy 返回:该地址返回的不是真正的图片数据 改用 /api/extract 返回的 iconUrl 或 candidates[].url

OpenAPI spec and MCP server

  • OpenAPI 3 spec: https://favicondl.com/openapi.yaml — import it into Postman, Insomnia or a client generator.
  • MCP server: favicondl MCP (registry name io.github.sweesama/favicondl) exposes an extract_favicon tool so Claude, Cursor and other MCP clients can fetch icons.

使用限制

免费使用

无需注册,完全免费使用所有功能

合理使用

  • • 没有 API key,也没有公布固定配额
  • • 从网站本身找到的图标在边缘节点缓存 24 小时;回退到 Google/DuckDuckGo 的结果缓存 10 分钟
  • • 请在你自己的系统中缓存图标,避免批量抓取

商业使用

没有付费套餐,也没有 SLA。如果是高频或关键业务使用,请把需要的图标保存到你自己的存储中。

已复制!