晓织云梯 · API 接口清单
象晓羊 · 发布于 2026-11-08 13:27:00 · 更新于 2026-11-22 13:33:52 · 95
晓织云梯 · API 接口清单
发布方:晓织云梯 · 本文档为接口速查表,完整接入流程见《第三方注册与登录接入说明》。
API 文档 - 晓织云梯
API 系统 · 接口清单
当前仅开放以下三组指令:文件集下载、第三方登录、第三方注册。其余接口一律返回 404/403,不在本文档列出。
您已登录。ApiKey 请在 账号管理 中生成。
通用规则
入口:https://www.xiagoyn.cn/api(api 子域仅开放镜像下载,其余一律 404)。
携带 ApiKey:参数 apikey=你的密钥 或请求头 X-API-Key: 你的密钥(两者任选其一)。
限频规则:每个 IP 每分钟最多 30 次请求,超限返回 429。
响应格式:JSON,成功返回 {"ok": true, ...},失败返回 {"error": "...", "code": "..."}。
使用本站 API 的第三方必须标注来源:「数据来源:晓织云梯」,详见 《第三方API请求代码示例文档》。
一、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请求权限密钥 |
| 必填。要接收验证码的邮箱(须为受支持域名) |
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位) |
| 必填。邮箱(须与接收验证码的邮箱一致,全站唯一) | |
| 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。
完整两步流程:
aao=sendcode→ 用户邮箱收到 6 位验证码aao=register带code→ 注册成功,验证码立即失效
接入说明书(含 AI 提示词)
给 AI 编码助手或第三方开发者看的完整说明书:接口细节、错误码、接入步骤,末尾附一段可直接复制的提示词,让 AI 照着给网站加第三方登录。
纯文本链接可以直接丢给任何 AI;在线版带排版,适合人看。
OAuth 2.0 跳转授权
第三方站点想让用户「点一下就登录」、又不想经手密码时,走标准 OAuth 授权码流程。用户在本站授权页点「允许」,第三方服务端用 code 换 access_token,再用 Token 取公开资料。
| 用途 | 地址 |
|---|---|
| 申请应用 | /oauth/apply 需先登录本站,提交后等站长审核 |
| 授权页 | /oauth/authorize 浏览器跳转 |
| 换 Token | /oauth/token 服务端 POST |
| 取资料 | /oauth/userinfo 服务端带 Bearer |
接着看本页「四、第三方接入完整流程」
注册不走 OAuth,仍用 aao=register 加进阶密钥。
示例文档
第三方开发者请阅读 《第三方API请求代码示例文档》,内含 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 文案会说明具体冲突字段。
六、接入方必须遵守
- 页面或应用内标注「数据来源:晓织云梯」,未标注视为违规,密钥会被撤销。
- 不得在前端存储用户明文密码;Token 应存在服务端,按用户会话隔离。
- 不得把 aapirqp 下发到客户端,只能在后端调用 aao=register。
- 不得批量建号、刷接口或绕过限频;异常调用会被封禁并回收密钥。
- 用户资料仅用于该用户在本应用内的登录与展示,不得二次分发。
接口仅此三组,其余一律下线。使用即表示同意本站 协议与条款。
七、文档 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 等本机地址不再自动跳转。
本文另有纯文本版,无页面样式,可直接给 AI 或脚本抓取: /docs/third-party.md text/markdown