API 使用说明

通过 API 令牌，外部程序或 AI 可以编程式地调用接口创建和查询学习卡片。

鉴权方式

所有公开接口都需要在请求头中携带您的 API 令牌：

Authorization: Bearer sk_你的令牌

在「设置 → API 令牌」中创建令牌。完整令牌仅在创建时显示一次，请妥善保管。

基础地址

正式部署地址（所有接口均基于此地址）：

https://card.caprompt.com

例如生成卡片接口的完整地址为 https://card.caprompt.com/api/v1/generate。

POST/api/v1/generateAI 生成卡片

根据输入文本由系统 LLM 引擎生成学习卡片，并归属到令牌对应账户。

完整地址：https://card.caprompt.com/api/v1/generate

请求体示例

{
  "inputText": "apple",
  "preferredType": "english_word",
  "model": "qwen-plus"
}

curl 调用示例

curl -X POST https://card.caprompt.com/api/v1/generate \
  -H "Authorization: Bearer sk_你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"inputText":"apple","preferredType":"english_word","model":"qwen-plus"}'

GET/api/v1/cards查询卡片列表

分页查询当前账户的卡片，支持 cardType、favoritedOnly、page、pageSize、sort、order 过滤。

完整地址：https://card.caprompt.com/api/v1/cards

GET/api/v1/cards/{id}查询单张卡片

按卡片 ID 查询单张卡片详情；若不属于当前账户则返回 404。

完整地址：https://card.caprompt.com/api/v1/cards/{id}

查询参数（GET /api/v1/cards）

cardType按卡片类型过滤，如 english_word、concept、classical_chinese、chemical_equation。
favoritedOnly仅返回已收藏的卡片，传 true。
page页码，从 1 开始，默认 1。
pageSize每页条数，1–50，默认 12。
limitpageSize 的别名，兼容常见 REST 客户端习惯；两者都传时以 limit 为准。
q搜索关键字，匹配卡片标题、内容、摘要或输入文本。
sort排序字段：createdAt、updatedAt、savedAt、title、inputText，默认 savedAt。
order排序方向：asc 或 desc，默认 desc。

例如按创建时间取最新一张： /api/v1/cards?sort=createdAt&order=desc&pageSize=1

错误码

401未提供令牌、令牌无效、已撤销或已过期。
400请求体校验失败，字段缺失或格式错误。
404资源不存在，或不属于当前账户。
500服务器内部错误。

响应格式

成功响应统一为 success: true 包裹的数据；失败响应返回错误码与说明。

// 成功
{
  "success": true,
  "data": { ... }
}

// 失败
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API token."
  }
}