Setu API 前端使用文档

提供按条件检索图库内容的接口，支持多标签匹配、尺寸过滤、R18 分类、AI 过滤、关键字搜索以及时间区间查询。

---

在线调试（仅文档站）

在文档站中可以使用内置调试组件输入参数并发送请求查看返回结果：

在线 API 调试

快速测试接口连通性与返回结构（不会内置真实 API Key）

基础地址 baseUrl

当前请求地址： https://api.yukiryou.icu/setu/v2?num=1&r18=0

X-API-Key（仅用于本地/测试环境，不建议填写正式环境的真实 Key）

调用时会自动附带 Header： 当前不会添加 X-API-Key 头（可能被服务端拒绝）

查询参数（不含 ? ）

本仓库的 index.md / params.md / examples.md 主要给前端 / 调用方查看接口说明。

---

基本信息

• 主接口（需要 API Key）：/setu/v2
• 博客专用接口（无需 API Key）：/blog/setu
• 博客统计（无需登录，用于展示总调用次数）：/blog/stats

实际完整地址以部署域名为准，例如：

• 测试环境：http://localhost:9898
• 生产环境：https://api.yukiryou.icu

---

鉴权方式（/setu/v2）

/setu/v2 为通用插画接口，必须携带 API Key：

GET /setu/v2?num=1&r18=0

X-API-Key: sk-xxxx-xxxx-xxxx

• API Key 需要登录后台后创建
• 建议为不同用途创建不同 Key（例如：blog-key, bot-key）

注意：前端页面不要直接写死 API Key。

• 公开网页（博客、前端应用）建议：
  • 使用 /blog/setu（无需 Key，已做安全限制）
  • 或调用你自己的后端服务，让后端再去调用 /setu/v2，避免暴露 Key

---

博客专用接口说明

1. 随机一张插画 /blog/setu

• 方法：GET

• 鉴权：不需要 API Key

• 安全限制：

  • 只允许来自以下域名的请求（含子域）：
    • https://yukiryou.icu
    • https://yukiryou.top
    • http://localhost:4321（本地开发）
  • 同一 IP 每分钟最多 10 次
  • 命中 IP 黑名单的请求会被拒绝

• 参数：无（内部使用默认值）：

  • num = 1
  • r18 = 0
  • size = ["original"]
  • proxy = "i.yukiryou.top"

前端调用示例：

fetch('https://api.yukiryou.icu/blog/setu')
  .then(r => r.json())
  .then(data => {
    const imgUrl = data?.data?.[0]?.urls?.original;
    console.log('图片地址:', imgUrl);
  });

---

2. 博客总调用次数 /blog/stats

• 方法：GET
• 用途：在博客上展示“已为博客提供 xxx 张插画”
• 无需鉴权，可直接调用（同样受 CORS 限制）

示例：

fetch('https://api.yukiryou.icu/blog/stats')
  .then(r => r.json())
  .then(data => {
    console.log('博客累计调用次数:', data.totalCalls);
  });

---

通用插画接口 /setu/v2

• 方法：GET / POST
• 鉴权：必须带 X-API-Key 头
• 适合：
  • 自己的后端服务调用
  • 私有工具 / Bot / 不会直接暴露在浏览器端的场景

详细参数说明参考： params.md
调用示例与返回格式参考： examples.md

---

返回数据结构简要说明

以 /setu/v2 为例：

{
  "error": "",
  "data": [
    {
      "pid": 123456,
      "p": 0,
      "uid": 78910,
      "title": "作品标题",
      "author": "作者名",
      "r18": false,
      "width": 1200,
      "height": 800,
      "tags": ["tag1", "tag2"],
      "ext": "jpg",
      "aiType": 0,
      "uploadDate": 1700000000000,
      "urls": {
        "original": "https://i.yukiryou.top/img-original/xxx.jpg",
        "regular": null,
        "small": null,
        "thumb": null,
        "mini": null
      }
    }
  ]
}

字段说明（常用）：

• pid：作品 ID（Pixiv）
• p：多图作品中的第几张（p0, p1 ...）
• uid：作者 UID
• title / author：标题与作者
• r18：是否 R18
• width / height：原图尺寸
• tags：标签列表
• ext：图片扩展名（jpg/png 等）
• aiType：AI 标记（0 未知 / 1 非 AI / 2 AI）
• uploadDate：上传时间（毫秒）
• urls：根据请求 size 返回不同尺寸的 URL