REST API
Tabicon API 文档
用一个 GET 请求获取任意站点图标，适合导航站、内容聚合站、CMS 后台与 SaaS 控制台。文档已按参数、示例和返回码整理，减少碎片化阅读负担。
快速开始
请求成功返回 image/png，可直接作为 地址使用。若接口校验失败，会返回对应状态码与文本说明。仅访问 /api/get（不带 url）时返回服务健康文本。
获取 API Key
默认请先注册并在控制台创建 API Key；仅当后台启用访客模式且配置默认演示 Key 时，才可留空测试。
构造请求
使用 GET 方法请求 /api/get。url 必填，size 可选且非法值会回退到 64；key 可用查询参数传入，也支持 X-API-Key 请求头。
处理响应
成功返回 image/png 图标数据，可直接用于 标签。
错误处理
请求失败返回对应状态码，参考返回状态章节处理异常。
接口地址
使用以下端点获取网站图标。
GET
https://www.favicon.org.cn/api/get?url={domain}[&size={size}][&key={api_key}]
💡 提示
仅当后台启用访客模式且配置了默认演示 Key 时，才可省略 key 参数进行测试；生产环境建议始终显式传入有效 API Key。
参数说明
API 接口支持以下查询参数。
url
必填
目标站点域名或 URL，例如 `apple.com`、`https://github.com`。
size
可选
输出尺寸支持 `16/32/48/64/96/128/256/512`。默认 `64`，传入不支持的值会自动回退到 `64`。
key
可选
API Key。默认需要有效密钥；仅当后台启用访客模式且配置了默认演示 Key 时可留空。也支持通过 X-API-Key 请求头传入。
鉴权方式
接口支持通过查询参数或请求头传入 API Key。生产环境建议优先使用请求头方式。
方式一：Query 参数
适合直接拼接图片地址，例如前端 、静态页面或简单脚本。
Query
https://www.favicon.org.cn/api/get?url=example.com&size=128&key=YOUR_API_KEY方式二：X-API-Key 请求头
适合服务端调用、代理层转发或不希望 Key 直接暴露在 URL 中的场景。
cURL
curl -H "X-API-Key: YOUR_API_KEY" "https://www.favicon.org.cn/api/get?url=example.com&size=128"
JavaScript / fetch
const response = await fetch('https://www.favicon.org.cn/api/get?url=example.com&size=128', {
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const blob = await response.blob();
document.getElementById('favicon').src = URL.createObjectURL(blob);💡 提示
接口会优先读取 ?key=...；当查询参数未传入时，再读取 X-API-Key 请求头。若后台启用了访客模式且配置了默认演示 Key，也可留空测试。
返回状态
API 可能返回以下 HTTP 状态码。
- 200 请求成功，返回 `image/png` 图标数据。
- 400 参数错误：`url` 非法。
- 403 未授权或策略拒绝（如缺失/无效 Key、未开放访客访问、私网域名、白名单不匹配或权限校验失败）。
- 404 目标站点未找到可用图标。
- 426 站点策略要求 HTTPS。
- 429 请求频率过高，请稍后重试。
- 500 服务内部错误（缓存路径/写入异常）。
代码示例
以下示例展示如何在项目中集成 API。
HTML
<img src="https://www.favicon.org.cn/api/get?url=example.com&size=128&key=YOUR_API_KEY" alt="Favicon of example.com" />
JavaScript
const url = 'https://www.favicon.org.cn/api/get?url=example.com&size=128&key=YOUR_API_KEY';
document.getElementById('favicon').src = url;
PHP
$url = 'https://www.favicon.org.cn/api/get?' . http_build_query([
'url' => 'example.com',
'size' => 128,
'key' => 'YOUR_API_KEY'
]);
echo '<img src="' . htmlspecialchars($url) . '" alt="Favicon of example.com">';