跳转到主要内容

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

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

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

基本约定

  • 基址：https://app.windfonts.com/api
  • 只介绍查询类接口，全部是 GET。
  • 返回 JSON，外层结构固定：
{
  "code": 200,
  "message": "…",
  "data": { }
}

code 为 200 表示成功。

旧接口 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 参数里。

出错时

出错时返回：

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

不要依赖的字段

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

接下来读什么