字体元数据 REST API（维护中）

适合谁看：想用程序查询文风字体目录（字体列表、详情、分类、厂商）的开发者。只想在网页里用字体的，不需要这个 API，看《快速开始：一行代码用上中文网页字体》。

维护中： 这组接口目前暂时无法访问。下面按现有程序整理，接口恢复后会再核对一遍字段和示例。网页字体的 CSS 引用不受影响。

基本概念基本约定

Windfonts

文风字体服务是一项可以像请求前端资源库的在线字体（web fonts）服务。

字体列表

当前接口可通过参数分页查询文风字体库的字体列表

请求地址

基址：POST https://app.windfonts.com/api/fonts/listapi 只介绍查询类接口，全部是 GET。

提示：该接口正在维护，暂时无法访问。恢复后会在本页更新。网页里使用字体，可以先按《网页字体引用与

返回 CDNJSON，外层结构固定： 接入》直接引用字体的 CSS。

查询条件

接口支持查询参数如下

Body	属性类型	属性描述	是否必传
pageData	object{page:number,size:number}	分页信息	是
tags	string	标签	否
category	string	分类	否
keyword	string	关键词	否

提示: 你可以一次传多个参数.

查询参数示例

{
  "pageData": {
    "page": 1,
    "size": 5
  }
}

响应数据

该接口返回的是一个对象结构

数据返回结构

属性名	数据类型	描述
code	number	响应状态码
message	string	响应状态信息
data	object	数据主体（对象），字体列表在 dataList 里

data

属性名	数据类型	描述
dataList	array	字体列表信息
page	number	分页，当前第几页
pageTotal	number	总页数
total	number	字体总数

dataList

属性名	数据类型	描述
id	string	唯一id
name	string	字体名称
fontFamily	string	字体使用名称 – 可用于设置css属性font-family
fontSubfamily	array（字符串数组）	子字体名称 – 可用于设置css属性font-weight
version	string	版本号
copyright	string	版权信息
description	string	描述信息
designer	string	设计者
license	string	使用协议地址
tags	string	字体标签
languages	string	字体适用语言
category	string	字体分类
created_at	string	创建时间
updated_at	string	更新时间

下面是一个详细的返回数据例子

{
  "code": 200,
  "message": "…",
  "data": { "page":}
1,}
"total":

100,

code "pageTotal":为 20,200 "dataList":表示成功。

[

旧接口 POST /api/fonts/list 已经下线，请改用下面的 GET /api/fonts。

认证和额度

不带密钥也能调用，但每天有基础额度（100 次）。超过后返回 429。 需要更高额度请联系文风。拿到密钥后，任选一种方式放在请求头里：

X-API-Key: 你的密钥
Authorization: Bearer 你的密钥

不要把密钥写进公开网页的前端代码。 不要在每次打开页面时都去拉整份字体列表。列表可以在构建网站时拉一次存下来，详情按需再查。

字体列表

GET /api/fonts

参数 说明 page 页码，从 1 开始，默认 1 size 每页条数，默认 20，最大 100 categoryId 分类 ID，见下面「分类」 brandId 厂商 ID，见下面「厂商」 search 关键词，也可以写成 q tags 标签，多个用英文逗号分隔 sort 排序字段：name、createdAt、viewCount、downloadCount order asc 或 desc

示例：

GET https://app.windfonts.com/api/fonts?page=1&size=20&sort=viewCount&order=desc

data 的结构：

字段 说明 total 符合条件的字体总数 page 当前页 pageTotal 总页数 dataList 本页字体，每项是一款字的元数据，并带上所属分类和厂商

单款字体

GET /api/fonts/{id 或目录名}

路径里可以写字体 ID，也可以写目录名（字体页网址最后一段），例如 /api/fonts/xwwk。

同一款字还有两个附加接口：

接口 说明 GET /api/fonts/{id 或目录名}/analysis 字符覆盖分析。没有分析数据时返回 404 GET /api/fonts/{id 或目录名}/estimate?subset=full 各子集的体积预估。subset 可取 en、zh-common、zh、full

分类和厂商

GET /api/categories
GET /api/brands

分别返回全部分类、全部厂商（品牌）。拿到的 ID 可以用在字体列表的 categoryId、brandId 参数里。

出错时

出错时返回：

{ "name"code": 429, "errorCode": "string",
        "fontFamily": "string",
        "fontSubfamily": ["string"],
        "version": "string",
        "copyright": "string",
        "description": "string",
        "designer": "string",
        "license": "string | null",
        "category": "string",
        "tags": "string",
        "languages": "string",
        "id": "string",
        "created_at": "date",
        "updated_at": "date"
      }
    ]
  }rate_limited", "message": "success"…" }

HTTP 状态 errorCode 含义 401 invalid_api_key_format 密钥格式不对 403 domain_blocked 来源网站被拒绝访问 429 rate_limited 超过当天额度 500 internal_error 服务端出错

不要依赖的字段

dataList 和单款详情里会带不少字段。除了上面写到的，其余字段可能随时调整，接口恢复后会再核对并在《更新记录》 里说明。

接下来读什么

《开发常见问题》 《更新记录》