<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 访问量计数器

> SVG/JSON访问量计数器，支持多套动效主题卡片（咒纹夜/术式蓝焰/五条悟风/无量空处/宿傩咒印等），可嵌入GitHub README或网站。按站点隔离计数。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `visits-counter` |
| 接口名称 | 访问量计数器 |
| 接口地址 | `https://v1.apizero.cn/api/visits-counter` |
| 请求方法 | `GET` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 1000 次（已认证用户） |
| 匿名每日额度 | 500 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名调用 500 次/天，登录后 1000 次/天，API Key 按你的额度计算。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `site` | `string` | 否 | 站点标识，用于区分不同来源（建议传你的域名）。不传时全局共享一个计数器。 | `apizero.cn` |
| `name` | `string` | 否 | 计数器名称，同一站点下可挂多个不同位置（首页/产品页/文章页等）。默认 demo。 | `home` |
| `mode` | `string` | 否 | 计数模式：daily=每日清零 / total=累计不清零。默认 daily。 | `total` |
| `theme` | `string` | 否 | 主题：默认 gojo_board（像素角色举牌+数字 GIF 动画）。可选 gojo_board/hoops_board/zero_board/jjk_infinity/rule34/moebooru/gelbooru/cursed_night/seal_blue/talisman_red/void_gold/gojo_satoru/infinity_void/sukuna_mark。前 7 个为像素牌主题（角色帧动画），后 7 个为 SVG 渐变主题。 | `gojo_board` |
| `format` | `string` | 否 | 输出格式：svg（默认，可直接 <img> 嵌入网页）/ png（静态图，scale=1~4）/ json（原始 JSON 数据，便于自集成）。 | `svg` |
| `length` | `int` | 否 | 数字位数 4~12，默认 7（前导补 0）。 | `7` |
| `no_increment` | `int` | 否 | 只读模式：1=只查询不递增（适合预览/调试）。默认 0。 | `0` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/visits-counter?site=apizero.cn&name=home&mode=total&theme=gojo_board&format=svg&length=7&no_increment=0&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `code` | `string` | 业务码：200 成功，4xxx/5xxx 错误 | — |
| `desc` | `string` | 业务描述（success / 错误原因） | — |
| `data` | `object` | 业务数据（仅 format=json 时返回；format=svg/png 时直接返回图片二进制） | — |
| `data.name` | `string` | 计数器名称（与请求参数 name 一致） | — |
| `data.mode` | `string` | 计数模式：daily / total | — |
| `data.theme` | `string` | 生效的主题键（不识别会回退 gojo_board） | — |
| `data.theme_name` | `string` | 主题中文名（前端可直接显示） | — |
| `data.value` | `int` | 当前计数值（按 mode 取 daily 或 total） | — |
| `data.display_value` | `string` | 前导补 0 的展示值，与 SVG 上数字一致 | — |
| `data.record` | `object` | 完整计数记录 | — |
| `data.record.total` | `int` | 历史累计计数 | — |
| `data.record.daily` | `int` | 今日计数 | — |
| `data.record.day` | `string` | 今日日期（YYYY-MM-DD） | — |
| `data.record.updated_at` | `string` | 记录最近更新时间（ISO8601） | — |
| `data.incremented` | `bool` | 本次调用是否已自增 | — |
| `data.step` | `int` | 本次自增步长 | — |
| `data.length` | `int` | 生效的数字位数 | — |
| `data.format` | `string` | 生效的输出格式 | — |
| `tips` | `string` | 提供方提示 | — |

## 7. 响应示例

```json
{
  "code": "200",
  "desc": "success",
  "data": {
    "name": "home",
    "mode": "daily",
    "theme": "gojo_board",
    "theme_name": "像素牌-苍空",
    "value": 42,
    "display_value": "0000042",
    "record": {
      "total": 1024,
      "daily": 42,
      "day": "2026-05-09",
      "updated_at": "2026-05-09T21:48:52+08:00"
    },
    "incremented": true,
    "step": 1,
    "length": 7,
    "format": "json"
  },
  "tips": "极数本源 · https://apizero.cn"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `200` | `—` | 成功 |
| `4015` | `—` | API Key 缺失或非法（v1 网关层） |
| `4029` | `—` | 触发 QPS 限频（v1 网关层） |
| `4030` | `—` | 触发当日免费/付费配额（v1 网关层） |
| `4044` | `—` | 接口已下线（v1 网关层） |
| `5021` | `—` | 本地渲染服务异常：server.py 不可达 / 超时 / 返回非预期 MIME |

## 9. 变更日志

- **1.0.0** (2026-05-08)
  - 首次上线
  - 支持7套动效主题
  - 按站点隔离计数

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/visits-counter`

Source: `https://apizero.cn/aidocs/visits-counter/raw.md`
Last updated: 2026-05-09T21:49:54+08:00