API v1
公开 REST API 文档
面向开发者的只读接口：按分类、标签、字母或关键词检索本站品牌矢量图标（SVG）。响应为 JSON，所有资源地址均为相对路径，调用方自行拼接自己的域名或本站域名即可。
交互式控制台
浏览器里直接试调所有公开端点，demo key 已预填（免费，限流 60 次/分，带 key 配额 ×10）。
检索品牌矢量图标，支持分类/标签/字母/关键词过滤与分页
查询参数
GET /api/v1/svgs
检索品牌矢量图标（94848+ 池内可直接命中，分页返回）。
curl "https://your-domain.example/api/v1/svgs?category=technology&page=1&limit=50"查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| category | string | 否 | 按分类过滤，slug 见 /api/v1/categories，如 technology、finance-banking |
| tag | string | 否 | 按标签过滤，slug 形态如 social-media |
| letter | string | 否 | 按首字母过滤：A-Z 单字母、0-9（数字开头）、other（其他首字母） |
| search | string | 否 | 关键词过滤（对图标名做包含匹配），如 chrome、arrow |
| keys | string | 否 | 按 routeKey 批量精确获取（16 位 hex 逗号分隔，1-50 个，非法项忽略），传入后优先于其他过滤与分页，响应为 { data, total } |
| page | number | 否 | 页码，从 1 开始，默认 1 |
| limit | number | 否 | 每页条数，1-200，默认 50 |
响应字段（data[]）
| 字段 | 类型 | 说明 |
|---|---|---|
| title | string | 图标名称（如 Chrome、youtube） |
| category | string | 首个分类 slug（与 /api/v1/categories 的 slug 对应，未分类为空串） |
| route | string | SVG 资产相对路径（/library/*.svg），可直接 <img src> 引用 |
| url | string | 品牌官网（缺失为空串） |
| detailUrl | string | 本站详情页相对路径（/svg/item-{routeKey}） |
{
"data": [
{
"title": "Chrome",
"category": "科技互联网",
"route": "/library/icon-b0005e0fd2a4b0355033b765.svg",
"url": "https://chrome.com/",
"detailUrl": "/svg/item-b0005e0fd2a4b0355033b765"
}
],
"page": 1,
"limit": 50,
"total": 128,
"totalPages": 3
}GET /api/v1/categories
返回全部 SVG 分类（slug / name / count）与分组信息，作为 /api/v1/svgs 的 category 参数字典。
curl "https://your-domain.example/api/v1/categories"GET /api/v1/icons/random
目录池内不重复随机抽样，适合「每日一图」「随机灵感」类集成场景；条目结构与 /api/v1/svgs 的 data[] 一致。
curl "https://your-domain.example/api/v1/icons/random?count=4"| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| count | number | 否 | 返回条数，1-12，默认 1；每次请求结果均不同（响应禁缓存） |
CDN 直链引用
不想调接口？每个图标都有稳定的 SVG 直链（带 immutable 长缓存），HTML、Markdown、README 里一行引用即可。routeKey 可从 /api/v1/svgs 响应或图标详情页 URL 获得。
<!-- HTML -->
<img src="https://your-domain.example/library/icon-b0005e0fd2a4b0355033b765.svg" width="32" alt="Chrome" />
<!-- Markdown（GitHub README）-->
响应头为 Cache-Control: immutable，适合直接前置自己的 CDN；需要换色、描边参数化请用详情页的复制格式（CSS mask / currentColor SVG）。
Figma 插件
官方 Figma 插件安装包：下载 zip 后在 Figma 中依次进入 Plugins → Development → Import plugin from manifest… 选择解压出的 manifest.json 即可在画布内搜索并插入本站图标。
MCP Server（AI 工作流）
端点 POST /api/mcp 实现 Model Context Protocol（Streamable HTTP，无状态 JSON 模式），提供 3 个工具，可在 Claude、Cursor 等 AI IDE 中直接检索与获取本站图标。
| 工具 | 参数 | 说明 |
|---|---|---|
| search_icons | query（中英文均可）、category?、tag?、limit? | 语义检索（中文同义词 + 拼音互译），返回 name/key/分类/标签 |
| get_icon_detail | key | 体积/viewBox/图元/品牌主色/健康评分分析报告 |
| get_svg_source | key | 返回完整 SVG 源码文本，可直接写入本地文件 |
# 手动调用（JSON-RPC 2.0）
curl -X POST https://your-domain.example/api/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_icons","arguments":{"query":"箭头","limit":5}}}'使用约定
- · 接口只读、免鉴权，响应带 CORS 头（Access-Control-Allow-Origin: *），浏览器可直接调用。
- · 图标内容归其品牌方所有，请遵循各图标库的开源协议与品牌使用规范，请勿用于商标注册或误导性用途。
- · route 为相对路径：拼接本站域名可直接引用 SVG 资产，也可代理到自己的对象存储。
速率限制
所有 /api/v1 端点限流 60 次/分钟/IP；每次响应附带 X-RateLimit-Limit 与 X-RateLimit-Remaining 响应头。超额时返回 429 与 Retry-After（秒），请按该间隔退避重试。
批量任务可在请求头携带 x-api-key（联系我们获取），配额提升为 10 倍。
| 端点 | 限额（每分钟/IP） | 说明 |
|---|---|---|
| /api/v1/* | 60 | 分类 / 图标 / 随机 |
| /api/search | 60 | 跨频道搜索（含语义召回） |
| /api/vector-search | 12 | 向量检索 / 以图搜图（计算开销大） |
| /api/v1/visual-search | 12 | 以图搜图 v1 版（POST image data uri，语义相似品牌图标召回） |
| /api/rate · /api/request | 20 / 30 | 评分与投票（写操作更低） |
框架快速开始
三分钟接入：React Hook / Vue 组合式 / 纯 HTML / 命令行四种方式，替换 YOUR_API_KEY 为你自己的 key（/account 创建）。
import { useEffect, useState } from 'react';
// 1. 拉取图标（可携带你的 x-api-key 提升配额）
function useIcons(params: Record<string, string> = {}) {
const [data, setData] = useState<{ title: string; route: string }[]>([]);
useEffect(() => {
const qs = new URLSearchParams(params).toString();
fetch(`https://your-domain.example/api/v1/svgs?${qs}`)
.then((r) => r.json())
.then((res) => setData(res.data ?? []));
}, []); // 依赖按需补齐
return data;
}
// 2. 渲染（route 为相对路径，直接 <img> 引用）
export function IconList() {
const icons = useIcons({ category: 'technology', limit: '12' });
return (
<div className="grid grid-cols-6 gap-2">
{icons.map((it) => (
<img key={it.route} src={`https://your-domain.example${it.route}`} alt={it.title} width={32} height={32} />
))}
</div>
);
}
