← 返回文档集

晓织云梯 · API 接口清单

教程文档

象晓羊 · 发布于 2026-11-08 13:27:00 · 更新于 2026-11-22 13:34:02 · 96

晓织云梯 · 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请求权限密钥
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请求权限密钥

接入说明书(含 AI 提示词)

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

在线查看

纯文本版(给 AI 直接抓)

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

OAuth 2.0 跳转授权

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

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

申请 OAuth 应用

接着看本页「四、第三方接入完整流程」

注册不走 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 固定,不要每次随机生成。

五、错误码对照表

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

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

六、接入方必须遵守

  1. 页面或应用内标注「数据来源:晓织云梯」,未标注视为违规,密钥会被撤销。
  1. 不得在前端存储用户明文密码;Token 应存在服务端,按用户会话隔离。
  1. 不得把 aapirqp 下发到客户端,只能在后端调用 aao=register。
  1. 不得批量建号、刷接口或绕过限频;异常调用会被封禁并回收密钥。
  1. 用户资料仅用于该用户在本应用内的登录与展示,不得二次分发。

接口仅此三组,其余一律下线。使用即表示同意本站 协议与条款。

七、文档 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

评论(0)

请先 登录 后参与评论

暂无评论,来抢沙发吧