API 文档 v1

IconSVR 提供免费、无鉴权的 SVG 图标 API 服务。通过简单的 HTTP GET 请求即可获取 IoT 图标，支持实时自定义颜色和尺寸。

🔄 版本迁移： 旧版 /api/svg.php 路径仍然可用，但建议迁移到新版 /api/v1/icon/{name} 路径，以获得更好的 RESTful 体验和标准化错误响应。

快速开始

在 HTML 中直接使用 <img> 标签引用：

<img src="https://iconsvr.com/api/v1/icon/temperature-sensor?cat=device&color=e34f32&size=48"
     alt="Temperature Sensor">

API 端点总览

方法端点响应格式说明
GET/api/v1/icon/{name}SVG获取单个 SVG 图标
GET/api/v1/iconsJSON图标列表（分页、搜索、分类过滤）
GET/api/v1/searchJSON全文搜索（带评分）
GET/api/v1/categoriesJSON分类列表
GET/api/v1/statsJSON服务统计
GET/api/svg.phpSVGV1 兼容（仍可用，建议迁移）

获取 SVG 图标

GET /api/v1/icon/{name}
参数位置类型必填说明示例
namePathstring✅ 是图标 slug（kebab-case）temperature-sensor
catQuerystring否分类 slug，加速查找device
colorQuerystring否十六进制颜色值（不含 #）e34f32
sizeQueryint否图标尺寸（px），范围 12-512，默认 2448
strokeQueryfloat否描边宽度，范围 0.5-101.5
variantQuerystring否图标变体（filled, outlined）outlined
formatQuerystring否响应格式（值为 json 时返回元数据）json

请求示例

基础调用

GET /api/v1/icon/plc-controller?cat=device

自定义颜色

GET /api/v1/icon/wifi?cat=communication&color=0066cc

自定义颜色和尺寸

GET /api/v1/icon/alarm?cat=status&color=dc2626&size=64

自定义描边

GET /api/v1/icon/gauge?cat=interface&color=059669&size=48&stroke=1.5

获取 JSON 元数据

GET /api/v1/icon/plc-controller?format=json

图标列表（JSON）

GET /api/v1/icons
参数类型必填说明示例
catstring否分类过滤device
qstring否搜索关键词（名称、标签、描述）传感器
pageint否页码，默认 12
per_pageint否每页数量，默认 50，最大 200100
sortstring否排序：newest, name, popularpopular
GET /api/v1/icons?cat=device&q=传感器&page=1&per_page=20&sort=newest

响应示例：

{
  "total": 160,
  "page": 1,
  "per_page": 50,
  "total_pages": 4,
  "category": "device",
  "icons": [
    {
      "id": 1,
      "name": "plc-controller",
      "slug": "plc-controller",
      "category": "device",
      "category_name": "设备",
      "tags": ["plc", "控制器"],
      "viewbox": "0 0 24 24",
      "file_size": 1847,
      "url": "https://iconsvr.com/api/v1/icon/plc-controller",
      "download_url": "https://iconsvr.com/icons/device/plc-controller.svg"
    }
  ]
}

全文搜索

GET /api/v1/search
参数类型必填说明
qstring✅ 是搜索关键词（1-100 字符）
catstring否限定分类
pageint否页码，默认 1
per_pageint否每页数量，默认 50，最大 200
GET /api/v1/search?q=温度&cat=device&page=1

响应示例：

{
  "query": "温度",
  "total": 3,
  "category": "device",
  "results": [
    {
      "id": 2,
      "name": "temperature-sensor",
      "slug": "temperature-sensor",
      "category": "device",
      "category_name": "设备",
      "match_type": "name",
      "score": 1.5,
      "url": "https://iconsvr.com/api/v1/icon/temperature-sensor"
    }
  ]
}

分类列表

GET /api/v1/categories
{
  "categories": [
    {
      "slug": "device",
      "name": "设备",
      "description": "PLC、传感器、执行器等物理设备",
      "icon_count": 45,
      "icon": "https://iconsvr.com/api/v1/icon/plc-controller?size=48&color=0066cc"
    }
  ]
}

服务统计

GET /api/v1/stats
{
  "service": "IconSVR",
  "version": "v1",
  "total_icons": 71,
  "total_categories": 6,
  "total_api_calls": 125430,
  "last_24h_calls": 3200,
  "top_icons_7d": [...],
  "endpoints": { ... }
}

响应格式

SVG 端点返回 Content-Type: image/svg+xml，JSON 端点返回 Content-Type: application/json。

公共响应头

Header值
Content-Typeimage/svg+xml; charset=utf-8 或 application/json; charset=utf-8
Access-Control-Allow-Origin*
Cache-Controlpublic, max-age=600（JSON）/ public, max-age=604800, immutable（SVG）
X-Served-Byiconsvr.com
X-API-Versionv1
X-RateLimit-Limit900（每分钟）

错误响应

JSON 端点返回标准化错误：

{
  "error": "not_found",
  "message": "图标 'xxx' 不存在",
  "code": 404
}
HTTP Code错误类型说明
400invalid_name图标名称格式无效
400invalid_color颜色格式无效
400invalid_size尺寸超出范围
400missing_param缺少必要参数
404not_found图标不存在
429rate_limited请求频率超限
500server_error服务内部错误

图标分类

分类slug说明
设备devicePLC、传感器、执行器、控制器等物理设备
通信communicationWiFi、BLE、Zigbee、LoRa、MQTT 等协议
状态status在线、离线、告警、正常等运行状态
场景scene工厂、能源、水务、楼宇等行业场景
界面interface仪表盘、开关、滑块、图表等 UI 控件
数据data数据库、时序数据、边缘计算等

使用场景

限制说明