小猫考试荣誉证书 API 文档

动态生成个性化电子荣誉证书，专为“小猫考试”粉丝排名设计。
域名：https://api.holytreasure.cn
协议：HTTPS + HTTP/2 + QUIC
认证：无需认证（公开接口）
限流策略：每个 IP 每分钟最多 3 次请求

---

📌 接口概览

功能	路径	方法	限流
生成荣誉证书	/api/certificates/generate	GET	✅ 每 IP ≤ 3 次/分钟

---

🎫 1. 生成荣誉证书

请求地址

GET https://api.holytreasure.cn/api/certificates/generate

请求参数（Query String）

参数	类型	必填	说明
rank	integer	是	用户排名，取值范围：1 ~ 999999

⚠️ 若参数缺失、非整数或超出范围，将返回错误。

---

✅ 成功响应（HTTP 200）

{
  "success": true,
  "rank": 888,
  "image_url": "https://api.holytreasure.cn/certificates/certificate_888_1734567890.png"
}

字段说明：

• success: true 表示成功
• rank: 回显传入的排名
• image_url: 生成的证书图片公开访问链接（PNG 格式，永久有效）

---

❌ 错误响应

1. 参数错误（HTTP 400）

{
  "success": false,
  "message": "参数 rank 必须是 1~999999 的整数"
}

2. 请求过于频繁（HTTP 429）

{
  "success": false,
  "message": "请求过于频繁，请稍后再试"
}

🔒 触发条件：同一 IP 在 60 秒内请求超过 3 次

3. 服务器内部错误（HTTP 500）

{
  "success": false,
  "message": "奖状生成失败，请稍后再试"
}

---

🖼 证书样式说明

• 背景：基于官方高清模板（含“荣誉证书”标题与装饰）
• 正文内容：

  恭喜你成为小猫考试第 {rank} 名粉丝
  特颁此奖状以资鼓励！

• 落款格式（右对齐，书信风格）：
  • 第一行：小猫考试组委会
  • 第二行：生成日期（如 2025年12月23日）
• 字体颜色：黑色
• 输出格式：PNG（无损压缩，清晰度高）

---

⚙️ 技术特性

特性	说明
限流机制	Nginx limit_req，基于真实客户端 IP
并发安全	同一 rank 多次请求会生成新文件（不复用）
跨域支持	✅ 支持 CORS，前端可直接调用
CDN 友好	图片路径固定，可被缓存
HTTPS 安全	强制 TLS 1.2+，HSTS 启用

---

💡 使用示例

JavaScript (Fetch)

async function generateCertificate(rank) {
  try {
    const res = await fetch(
      `https://api.holytreasure.cn/api/certificates/generate?rank=${rank}`
    );
    const data = await res.json();

    if (data.success) {
      const img = document.createElement('img');
      img.src = data.image_url;
      document.body.appendChild(img);
    } else {
      console.error('API Error:', data.message);
    }
  } catch (err) {
    console.error('Network Error:', err);
  }
}

// 调用示例
generateCertificate(123);

cURL

# 正常请求
curl "https://api.holytreasure.cn/api/certificates/generate?rank=1"

# 批量测试限流（第4次将返回429）
for i in {1..4}; do
  curl -s "https://api.holytreasure.cn/api/certificates/generate?rank=999"
  echo
done

---

📞 技术支持

• 维护团队：HolyTreasure 开发组
• 问题反馈：holytreasure@163.com
• 服务状态：稳定运行中（部署于阿里云 ECS）

🎁 祝你在小猫考试中取得好成绩！
—— 小猫考试组委会 · 荣誉证书系统 v2

---

• 分类： 未分类
• 标签： 无标签