# 晓织云梯 · API 接口清单

> 发布方：晓织云梯 · 本文档为接口速查表，完整接入流程见《第三方注册与登录接入说明》。

API 文档 - 晓织云梯

# API 系统 · 接口清单

当前仅开放以下三组指令：文件集下载、第三方登录、第三方注册。其余接口一律返回 404/403，不在本文档列出。

您已登录。ApiKey 请在 [账号管理](/users/) 中生成。



## 通用规则

入口：https://www.xiagoyn.cn/api（api 子域仅开放镜像下载，其余一律 404）。

携带 ApiKey：参数 apikey=你的密钥 或请求头 X-API-Key: 你的密钥（两者任选其一）。

限频规则：每个 IP 每分钟最多 30 次请求，超限返回 429。

响应格式：JSON，成功返回 {"ok": true, ...}，失败返回 {"error": "...", "code": "..."}。

使用本站 API 的第三方必须标注来源：「数据来源：晓织云梯」，详见 [《第三方API请求代码示例文档》](/docs/6)。

## 一、aao=downloads · 文件集下载

获取文件集的所有文件列表（按文件集取件码），或获取文件集中的一个文件。

| 参数 | 说明 |
| --- | --- |
| apikey | 不需要。文件集下载接口免密钥 |
| aao | 必填。downloads |
| id | 必填。文件集取件码 |
| fid | 可选。文件序号，从 0 开始、0 最旧；不传则返回整个文件集的全部文件列表，超出范围返回 404 |

```
GET https://www.xiagoyn.cn/api?aao=downloads&id=文件集取件码
GET https://www.xiagoyn.cn/api?aao=downloads&id=文件集取件码&fid=文件序号（0 起）
```

返回：文件列表/单个文件的 index（集内序号，0 起）/ id（全局ID）/ code / display_name / size_bytes / downloads_count / max_downloads / created_at / download_url / preview_url（可预览时，统一为 /preview-file?url=...）。

## 二、aao=login · 第三方登录

适合第三方网站或应用：用本站账号直接登录，免做复杂注册逻辑。凭 xgid（或用户ID、邮箱）+ 密码换取 Token。

| 参数 | 说明 |
| --- | --- |
| aao | 必填。login |
| xgid | 必填。XGID / 用户ID / 邮箱，三者任选其一作为账号标识（旧参数名 ywuid 仍兼容） |
| password | 必填。账号密码 |
| rlt | 必填。登录标题，用于账号设备管理显示的名称 |

```
GET https://www.xiagoyn.cn/api?aao=login&xgid=XGID&password=密码&rlt=第三方应用名
```

Token 有效期规则：如果该账号此前用相同标题登录过（仍在有效期内），则本次 Token 为 30 天；若是新标题，则为 7 天。

返回：token / login_days / rlt / issued_at（Token分发日期）/ expires_at（Token结束日期）/ ywuid / username。

## 三之一、aao=sendcode · 发送注册邮箱验证码

注册前先调本接口，把 6 位验证码发到用户邮箱。**验证码 5 分钟内有效，同一邮箱 60 秒内只能发一次。** 必须携带进阶API请求权限密钥（aapirqp），无需 ApiKey。

| 参数 | 说明 |
| --- | --- |
| aao | 必填。sendcode |
| aapirqp | 必填。进阶API请求权限密钥 |
| email | 必填。要接收验证码的邮箱（须为受支持域名） |

```
GET https://www.xiagoyn.cn/api?aao=sendcode&aapirqp=进阶密钥&email=用户邮箱
```

返回：`{"ok": true, "message": "验证码已发送到该邮箱，5 分钟内有效", "expires_in": 300}`

## 三、aao=register · 第三方注册

第三方网站或应用代用户注册本站账号。**必须先调用 `aao=sendcode` 获取邮箱验证码，注册时带上 `code`**，否则一律拒绝——这是防止批量违规建号的门槛。不允许普通用户使用，必须携带进阶API请求权限密钥（aapirqp），无需 ApiKey。该密钥通过下方申请按钮向站长申请，审核通过后签发。

| 参数 | 说明 |
| --- | --- |
| aao | 必填。register |
| aapirqp | 必填。进阶API请求权限密钥（经审核签发的 akx_ 开头密钥） |
| code | **必填。邮箱验证码，6 位数字，由 aao=sendcode 下发，5 分钟内有效，用后即删除** |
| username | 必填。用户名（1-14字符，不可用保留名） |
| password | 必填。密码（至少6位） |
| email | 必填。邮箱（须与接收验证码的邮箱一致，全站唯一） |
| birthday | 可选。生日，YYYYMMDD 8位 |
| gender | 可选。男 / 女 |
| xgid | 可选。XGID（5-12位，字母/数字/下划线）；不填则留空（旧参数名 ywuid 仍兼容） |
| agreed_terms | 必填。1（同意全部协议与条款） |

```
GET https://www.xiagoyn.cn/api?aao=register&aapirqp=进阶密钥&code=123456&username=名字&password=密码&email=邮箱&agreed_terms=1
```

返回：uuid / user_id / username / ywuid。

**完整两步流程：**

1. `aao=sendcode` → 用户邮箱收到 6 位验证码
2. `aao=register` 带 `code` → 注册成功，验证码立即失效

[申请进阶API请求权限密钥](/api/access/apply/)

## 接入说明书（含 AI 提示词）

给 AI 编码助手或第三方开发者看的完整说明书：接口细节、错误码、接入步骤，末尾附一段可直接复制的提示词，让 AI 照着给网站加第三方登录。

[在线查看](/docs/6)
[纯文本版（给 AI 直接抓）](/docs/third-party.md)

纯文本链接可以直接丢给任何 AI；在线版带排版，适合人看。

## OAuth 2.0 跳转授权

第三方站点想让用户「点一下就登录」、又不想经手密码时，走标准 OAuth 授权码流程。用户在本站授权页点「允许」，第三方服务端用 code 换 access_token，再用 Token 取公开资料。

| 用途 | 地址 |
| --- | --- |
| 申请应用 | /oauth/apply　需先登录本站，提交后等站长审核 |
| 授权页 | /oauth/authorize　浏览器跳转 |
| 换 Token | /oauth/token　服务端 POST |
| 取资料 | /oauth/userinfo　服务端带 Bearer |

[申请 OAuth 应用](/oauth/apply)
接着看本页「四、第三方接入完整流程」

注册不走 OAuth，仍用 aao=register 加进阶密钥。

## 示例文档

第三方开发者请阅读 [《第三方API请求代码示例文档》](/docs/6)，内含 Python / JavaScript / curl 代码示例与申请入口。

## 四、第三方接入完整流程

第三方站点或应用接入本站账号，分三步：拿密钥 → 建号（可选）→ 换 Token。

| 步骤 | 做什么 | 怎么操作 |
| --- | --- | --- |
| 1 | 拿密钥 | 只读文件集：在账号管理生成 ApiKey（sk-xiagoyn_ 开头）。需要替用户建号：先申请 进阶密钥（akx_ 开头），站长审核后签发。 |
| 2 | 建号（可选） | 调 aao=register，携带 aapirqp 与用户资料，返回 uuid / user_id / ywuid。已有账号的用户跳过这步。 |
| 3 | 换 Token | 调 aao=login，携带 xgid（或用户ID、邮箱）+ password + rlt（你的应用名），返回 token。 |
| 4 | 用 Token | 后续请求把 Token 放进 token 参数或 Authorization: Bearer Token，即可代表该用户调账号相关接口。 |

rlt 是你的应用标识，同名再次登录 Token 有效期延长到 30 天，换名则按新设备算 7 天。请保持 rlt 固定，不要每次随机生成。

## 五、错误码对照表

| HTTP | code | 含义与处理 |
| --- | --- | --- |
| 400 | CODE_REQUIRED | 注册未带邮箱验证码，先调 aao=sendcode |
| 400 | CODE_NOT_FOUND | 该邮箱还没有未过期的验证码 |
| 400 | CODE_INVALID | 邮箱验证码填错 |
| 400 | CODE_EXPIRED | 邮箱验证码超过 5 分钟，重新获取 |
| 400 | BAD_PARAM | 参数缺失或格式不对，按 error 文案补齐参数 |
| 401 | INVALID_CREDENTIALS | 账号或密码错误 |
| 401 | AUTH_REQUIRED | ApiKey 缺失或无效 |
| 401 | ADV_KEY_REQUIRED | 注册时未携带 aapirqp |
| 403 | ADV_KEY_INVALID | 进阶密钥未通过审核、已被封禁或不存在 |
| 403 | ACCOUNT_DISABLED | 账号被禁用或处于注销流程 |
| 404 | NOT_FOUND | 文件集不存在、为空，或 fid 不在该文件集内 |
| 409 | USERNAME_EXISTS | 用户名已被占用，换一个 |
| 429 | RATE_LIMITED | 请求过于频繁（每 IP 每分钟 30 次），退避后重试 |

注册接口的 409 可能由邮箱唯一引起，返回体 error 文案会说明具体冲突字段。

## 六、接入方必须遵守

1. 页面或应用内标注「数据来源：晓织云梯」，未标注视为违规，密钥会被撤销。

2. 不得在前端存储用户明文密码；Token 应存在服务端，按用户会话隔离。

3. 不得把 aapirqp 下发到客户端，只能在后端调用 aao=register。

4. 不得批量建号、刷接口或绕过限频；异常调用会被封禁并回收密钥。

5. 用户资料仅用于该用户在本应用内的登录与展示，不得二次分发。

接口仅此三组，其余一律下线。使用即表示同意本站 [协议与条款](/aat/)。

## 七、文档 API

### 7.1 搜索文档

`GET https://xiagoyn.cn/api/v1/docs/search`

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| api-key | 是 | 也支持请求头 `X-API-Key` |
| q | 否 | 关键词；匹配文档标题、分类名称、分类 slug 与文档 ID |
| category | 否 | 分类 slug，多个用逗号分隔；不传表示不限分类 |
| limit | 否 | 返回条数，默认 10，最大 50 |
| offset | 否 | 偏移量，默认 0 |

默认按最新排序，默认不限分类。返回 `id`、`title`、`categories`、`author_id`、`author_name`、`created_at`、`updated_at`、`views`、`url`。

### 7.2 获取单篇文档

`GET https://xiagoyn.cn/api/v1/docs/get?id=8`

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| api-key | 是 | 也支持请求头 `X-API-Key` |
| id | 是 | 文档 ID |

返回文档元信息与 `content`（Markdown 原文）、`content_type`（`text/markdown`）。

### 7.3 文档分类

`tutorial` 教程文档、`helper` 求助、`gameblock-游戏名` 游戏分类（例如 `gameblock-minecraft`）。一篇文档可挂多个分类，游戏类后缀需先在后台「文档分类」加入白名单。

## 八、公告 API（免密钥）

公告接口不要求 api-key，列表只返回标题与时间，正文用详情接口单独取。

### 8.1 获取公告列表

`GET https://xiagoyn.cn/api/v1/announcements`

`GET https://xiagoyn.cn/api?aao=announcements`

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| mode | 否 | `latest` 最新公告（默认取 1 条，可配合 limit 多取）、`important` 只取重要公告、`all` 全部公告；默认 `latest` |
| limit | 否 | 返回条数；`latest` 默认 1，其余默认 10，最大 50 |
| offset | 否 | 偏移量，默认 0 |
| category | 否 | `webannouncement` 网站公告、`webxiaogamesystem` 游戏平台公告、`xiaochunlauncher` 启动器公告；不传表示全部分类 |

返回 `ok`、`mode`、`count`、`total`、`limit`、`offset`、`items`。`items` 每项包含 `id`、`title`、`type`、`category`、`category_name`、`is_important`、`created_at`、`created_at_local`、`detail_url`、`web_url`，不含正文。

### 8.2 获取公告正文

`GET https://xiagoyn.cn/api/v1/announcements/13`

`GET https://xiagoyn.cn/api?aao=announcement&id=13`

返回 `announcement`：`id`、`title`、`content_md`（Markdown 原文）、`content_type`（`text/markdown`）、`created_at`、`created_at_local`、`category`、`category_name`、`type`、`is_important`、`detail_url`、`web_url`。

### 8.3 分类与重要公告

`webannouncement` 为网站公告，`webxiaogamesystem` 为游戏平台公告，`xiaochunlauncher` 为启动器公告。`type` 为 `重要公告` 的条目 `is_important` 为 `true`，`mode=important` 只取这些条目。所有公告均可通过 API 获取，无需密钥。

### 8.4 文件预览地址

文件类接口返回的 `preview_url` 统一为 `/preview-file?url=<URL 编码后的文件地址>`，浏览器直接打开即可内联预览，不扣下载次数。示例：

`https://xiagoyn.cn/preview-file?url=%2Fexpress%2Ff%2F225b6c84-b45f-43fb-a40d-d23ce0427660`
### 8.5 公告评论（需登录）

公告评论即时显示，不进入审核队列；每条评论与每条回复都带有「举报」入口。

`POST https://xiagoyn.cn/announcements/api/comment`

请求体为 JSON 或表单，字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| token | 是 | 登录会话 token，也可放在 Cookie 或 Authorization |
| announcement_id | 是 | 公告 ID |
| content | 是 | 评论正文，1 到 1000 字 |
| parent_id | 否 | 回复的评论 ID；`0` 或省略表示一级评论，只支持一层回复 |

成功后返回 `success`、`message` 和 `comment`（含 `id`、`announcement_id`、`parent_id`、`content`、`created_at`、`username`、`user_id`）。

限制：同一用户 3 秒内只能发 1 条，一天最多 50 条；只能回复同一公告下的一级评论，不能回复回复。

`POST https://xiagoyn.cn/announcements/api/delete-comment`

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| token | 是 | 登录会话 token |
| comment_id | 是 | 要删除的评论 ID |

评论作者本人、站主和管理员可删；删除一级评论时，它下面的回复会一起删除。

举报入口格式：`/report?target_type=other&target_id=announcement_comment-<评论ID>&target_label=<公告标题与评论ID>`。

### 8.6 预览与跳转安全

`/preview-file?url=...` 只在本站内联打开本站文件，任何外站地址都不会从该接口拿到 302 跳转；外站即使命中 `/go` 的网络白名单，也直接返回 403 `EXTERNAL_PREVIEW_DISABLED`，不在白名单返回 403 `EXTERNAL_NOT_ALLOWED`。

`url` 参数会先逐层解码 `%` 百分号编码，再检查协议、主机、账号信息、控制字符、反斜杠和协议相对地址；`%2F%2F`、双层 `%25`、`userinfo@`、`javascript:`、CRLF 等写法都会被拒绝。

`/go` 使用同一份网络白名单，自身也先解码再校验；本站地址可直达，白名单外站与带账号信息的地址进入确认页，`localhost`、`127.0.0.1`、`::1` 等本机地址不再自动跳转。
