调用示例与返回格式（前端视角）

本页给出常见调用方式，分别针对 通用接口 /setu/v2 和 博客专用接口 /blog/setu。

---

1. 通用接口 /setu/v2（需要 API Key）

适合：后端服务、Bot、不会暴露在浏览器源码中的场景。
浏览器前端不要直接写死 API Key。

1.1 GET 示例：获取 1 个非 R18 的随机图

GET /setu/v2?num=1&r18=0
X-API-Key: sk-xxxx-xxxx-xxxx

1.2 GET 示例：获取 5 张 original + regular 尺寸图片

GET /setu/v2?num=5&size=original&size=regular
X-API-Key: sk-xxxx-xxxx-xxxx

1.3 GET 示例：按标签和关键字筛选

GET /setu/v2?num=3&r18=0&tag=猫耳&tag=白发&keyword=白丝
X-API-Key: sk-xxxx-xxxx-xxxx

1.4 POST 示例（JSON 请求体）

POST /setu/v2
Content-Type: application/json
X-API-Key: sk-xxxx-xxxx-xxxx

{
  "num": 3,
  "r18": 0,
  "size": ["original", "regular"],
  "tag": ["猫耳", "白发"],
  "keyword": "白丝",
  "proxy": "i.yukiryou.top"
}

---

2. 博客专用接口 /blog/setu（无需 API Key）

适合：公开博客前端直接调用。已内置防滥用策略（域名白名单 + IP 限流）。

2.1 前端 JS 示例

async function loadBlogSetu() {
  const resp = await fetch('https://api.yukiryou.icu/blog/setu');
  const data = await resp.json();
  const item = data?.data?.[0];
  if (!item) return;

  const imgUrl = item.urls.original;
  const title = item.title;
  const author = item.author;

  console.log('随机图片:', imgUrl, '标题:', title, '作者:', author);
}

loadBlogSetu();

• 不需要 Header，也不需要参数
• 若当前页面域名不在白名单内，或调用过于频繁，可能返回 403 / 429

---

3. 博客统计 /blog/stats

用于在博客上显示“累计调用次数”。

async function loadBlogStats() {
  const resp = await fetch('https://api.yukiryou.icu/blog/stats');
  const data = await resp.json();
  console.log('博客累计调用次数:', data.totalCalls);
}

loadBlogStats();

---

4. 返回 JSON 示例

以 /setu/v2 或 /blog/setu 成功返回一条数据为例：

{
  "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/img/2025/01/01/00/00/00/123456_p0.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 返回）