API 文档 · 名言云

认证模块

3 个接口

POST /api/v1/auth/register

用户注册

邮箱 + 用户名 + 密码注册账号，注册成功即返回 Token，无需二次激活即可调用基础接口。

鉴权：无

请求参数

参数	类型	必填	默认	说明
email	string	是	—	邮箱地址，需符合邮箱格式
username	string	是	—	用户名，3-20 字符
password	string	是	—	密码，6-32 字符

请求示例

cURL

curl -X POST "https://my.lequ.pw/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "testuser",
    "password": "123456"
  }'

响应示例

response

{
  "code": 201,
  "message": "注册成功",
  "data": {
    "user": {
      "id": "uuid-xxx",
      "email": "user@example.com",
      "username": "testuser",
      "role": "user",
      "status": 1,
      "email_verified": 0,
      "created_at": "2026-07-16T10:00:00Z"
    },
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci..."
  }
}

POST /api/v1/auth/login

用户登录

使用邮箱与密码登录，返回 Access Token（15min）与 Refresh Token（7 天）。

鉴权：无

请求参数

参数	类型	必填	默认	说明
email	string	是	—	注册邮箱
password	string	是	—	登录密码

请求示例

cURL

curl -X POST "https://my.lequ.pw/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "123456"
  }'

响应示例

response

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "username": "testuser",
      "role": "user"
    },
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci..."
  }
}

GET /api/v1/auth/me

获取当前用户

获取当前登录用户的资料与会员状态。

鉴权：JWT

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/auth/me" \
  -H "Authorization: Bearer <accessToken>"

响应示例

response

{
  "code": 200,
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "testuser",
    "role": "user",
    "status": 1,
    "email_verified": 1,
    "membership": {
      "plan_name": "免费",
      "daily_quota": 100,
      "status": "active",
      "started_at": "2026-07-01T00:00:00Z",
      "expires_at": null
    }
  }
}

名言调用模块

5 个接口

GET /api/v1/quote/random

随机名言

随机返回一条名言。支持按分类筛选与批量获取，批量最多 10 条且仅计费 1 次。

鉴权：API Key 计费：是（count=1 算 1 次；count>1 仍算 1 次）

请求参数

参数	类型	必填	默认	说明
category	string	否	—	分类筛选，如：名人名言 / 诗词 / 经典台词
count	number	否	1	批量数量（1-10）。count=1 返回对象，>1 返回数组

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/quote/random?category=名人名言&count=1" \
  -H "X-API-Key: sk-xxxxxxxxxxxx"

响应示例

response

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 22,
    "category": "名人名言",
    "content": "千里之行，始于足下。",
    "author": "老子",
    "source": "道德经",
    "tags": ["行动", "坚持", "积累"]
  },
  "meta": {
    "provider": "杰哥",
    "provider_url": "https://my.lequ.pw",
    "remaining_today": 87
  }
}

GET /api/v1/quote/:id

名言详情

根据名言 ID 获取单条详情。

鉴权：API Key 计费：是

请求参数

参数	类型	必填	默认	说明
id	integer	是	—	名言 ID（路径参数）

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/quote/22" \
  -H "X-API-Key: sk-xxxxxxxxxxxx"

响应示例

response

{
  "code": 200,
  "data": {
    "id": 22,
    "category": "名人名言",
    "content": "千里之行，始于足下。",
    "author": "老子",
    "source": "道德经",
    "tags": ["行动", "坚持", "积累"]
  }
}

GET /api/v1/quotes

名言列表

分页查询名言列表，支持分类、作者、标签、关键词多条件组合筛选。

鉴权：API Key 计费：是

请求参数

参数	类型	必填	默认	说明
page	number	否	1	页码，从 1 开始
page_size	number	否	20	每页数量，最大 50
category	string	否	—	按分类筛选
author	string	否	—	按作者筛选
tag	string	否	—	按标签筛选
q	string	否	—	关键词搜索（全文检索）

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/quotes?page=1&page_size=20&category=诗词&author=苏轼" \
  -H "X-API-Key: sk-xxxxxxxxxxxx"

响应示例

response

{
  "code": 200,
  "data": [
    {
      "id": 211,
      "category": "诗词",
      "content": "长风破浪会有时，直挂云帆济沧海。",
      "author": "李白",
      "source": "行路难·其一",
      "tags": ["豪放", "励志", "理想"]
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1455
  }
}

GET /api/v1/categories

分类列表

获取全部分类及名言数量。该接口免费，不计入调用配额。

鉴权：无计费：否（免费）

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/categories"

响应示例

response

{
  "code": 200,
  "data": [
    { "id": 1, "name": "名人名言", "quote_count": 899, "sort_order": 1 },
    { "id": 2, "name": "诗词", "quote_count": 312, "sort_order": 2 },
    { "id": 3, "name": "经典台词", "quote_count": 156, "sort_order": 3 }
  ]
}

GET /api/v1/authors

作者列表

分页获取作者列表，支持关键词搜索。免费接口。

鉴权：无计费：否（免费）

请求参数

参数	类型	必填	默认	说明
page	number	否	1	页码
page_size	number	否	20	每页数量
q	string	否	—	作者名关键词

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/authors?page=1&page_size=20&q=孔"

响应示例

response

{
  "code": 200,
  "data": [
    { "id": 1, "name": "孔子", "dynasty": "春秋", "quote_count": 42 }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 173 }
}

密钥管理模块

2 个接口

GET /api/v1/keys

获取密钥列表

获取当前用户全部 API 密钥（仅返回前缀明文，完整密钥仅创建时返回一次）。

鉴权：JWT

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/keys" \
  -H "Authorization: Bearer <accessToken>"

响应示例

response

{
  "code": 200,
  "data": [
    {
      "id": "uuid",
      "key_prefix": "sk-abcde",
      "name": "默认密钥",
      "status": 1,
      "last_used_at": "2026-07-16T10:00:00Z",
      "created_at": "2026-07-16T09:00:00Z"
    }
  ]
}

POST /api/v1/keys

生成新密钥

一键生成新的 API 密钥，最多 3 个活跃密钥。完整密钥仅此一次返回，请妥善保管。

鉴权：JWT

请求体

body

{ "name": "我的密钥" }

请求示例

cURL

curl -X POST "https://my.lequ.pw/api/v1/keys" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "我的密钥" }'

响应示例

response

{
  "code": 201,
  "message": "密钥创建成功，请妥善保管，此密钥仅显示一次",
  "data": {
    "id": "uuid",
    "key": "sk-abc123xyz...",
    "name": "我的密钥",
    "created_at": "2026-07-16T10:00:00Z"
  }
}

用户模块

2 个接口

GET /api/v1/user/membership

获取会员状态

获取当前会员等级、日配额、当日已用与剩余次数。

鉴权：JWT

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/user/membership" \
  -H "Authorization: Bearer <accessToken>"

响应示例

response

{
  "code": 200,
  "data": {
    "plan_name": "免费",
    "daily_quota": 100,
    "status": "active",
    "started_at": "2026-07-01T00:00:00Z",
    "expires_at": null,
    "used_today": 13,
    "remaining_today": 87
  }
}

GET /api/v1/user/usage

用量统计

获取近 N 天的调用统计与汇总信息，默认 7 天。

鉴权：JWT

请求参数

参数	类型	必填	默认	说明
days	number	否	7	统计天数（7 / 30）

请求示例

cURL

curl -X GET "https://my.lequ.pw/api/v1/user/usage?days=7" \
  -H "Authorization: Bearer <accessToken>"

响应示例

response

{
  "code": 200,
  "data": {
    "records": [
      { "date": "2026-07-16", "call_count": 13 }
    ],
    "summary": {
      "total_calls": 89,
      "avg_daily": 12.7,
      "peak_day": "2026-07-15"
    }
  }
}

状态码与错误

统一错误响应格式

状态码	含义
200	成功
201	创建成功
400	请求参数错误
401	未认证 / Token 无效 / API Key 无效
403	无权限（非管理员）
404	资源不存在
429	调用次数超限
500	服务器内部错误

配额超限响应示例（429）

error response

{
  "code": 429,
  "message": "今日调用次数已用完，该服务由杰哥提供，升级会员解锁更多次数",
  "data": null,
  "upgrade_url": "https://my.lequ.pw/pricing"
}