{"openapi":"3.0.3","info":{"title":"TWL Open API","description":"世界盒子（WorldBox）模组 / 地图 / 游戏版本的镜像源与上传接口。\n\n**下载**接口完全公开；**上传**接口需要 `x-api-key` 请求头。\n\n索引接口返回与 TWL 源**完全兼容**的结构 —— 第三方启动器只需把索引地址的 base URL 换成这里，就能直接复用现有解析逻辑。","version":"1.0.0"},"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header","description":"在「汐语启动器 TWL」开发者处申请"}},"schemas":{}},"paths":{"/":{"get":{"summary":"服务首页（接口清单）","tags":["meta"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/health":{"get":{"summary":"健康检查","tags":["meta"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/stats":{"get":{"summary":"下载统计","tags":["meta"],"description":"累计下载总数、今日下载、最近 30 天趋势、下载排行 Top N。公开接口，不需要 key。","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1":{"get":{"summary":"API 说明","tags":["meta"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks":{"get":{"summary":"最近的上传任务列表","tags":["upload"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/quota":{"get":{"summary":"当前 API Key 的剩余额度","tags":["upload"],"description":"必须带有效的 x-api-key；无效或不带都返回 401。","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/keys":{"get":{"summary":"已配置的 API Key 列表（脱敏）","tags":["meta"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/mods":{"get":{"summary":"模组索引","tags":["catalog"],"description":"返回全部模组。默认是完全兼容现有 mods.json 的结构；加 ?format=rest 得到 REST 风格。","parameters":[{"schema":{"type":"string","enum":["compat","rest"]},"in":"query","name":"format","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/maps":{"get":{"summary":"地图索引","tags":["catalog"],"parameters":[{"schema":{"type":"string","enum":["compat","rest"]},"in":"query","name":"format","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/versions":{"get":{"summary":"游戏版本索引","tags":["catalog"],"parameters":[{"schema":{"type":"string","enum":["compat","rest"]},"in":"query","name":"format","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/android/versions":{"get":{"summary":"安卓游戏本体索引","tags":["catalog"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/dependencies":{"get":{"summary":"前置框架与模组加载器索引","tags":["catalog"],"parameters":[{"schema":{"type":"string","enum":["compat","rest"]},"in":"query","name":"format","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/mods/{uuid}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/maps/{uuid}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/mods/{uuid}/download":{"get":{"summary":"下载模组文件","tags":["download"],"description":"支持 Range 断点续传 / 多线程分片。","parameters":[{"schema":{"type":"string"},"in":"query","name":"gameversion","required":false},{"schema":{"type":"string"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/maps/{uuid}/download":{"get":{"summary":"下载地图文件","tags":["download"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"gameversion","required":false},{"schema":{"type":"string"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/versions/{version}/download":{"get":{"summary":"下载游戏本体","tags":["download"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"version","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/preview/{uuid}":{"get":{"summary":"模组 / 地图封面图","tags":["download"],"description":"按 uuid 取封面图，返回 image/*。图片不变，可长缓存。","parameters":[{"schema":{"type":"string"},"in":"path","name":"uuid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/framework/{name}":{"get":{"summary":"下载前置框架（BepInEx / NeoModLoader 等）","tags":["download"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true,"description":"bepinex 或具体文件名"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/upload":{"post":{"summary":"上传模组 / 地图 / 游戏版本","tags":["upload"],"description":"需要 x-api-key。文件先收完再返回 202，随后在后台写入源站并自动追加索引。用返回的 taskId 轮询 GET /api/v1/tasks/{taskId} 看进度。","parameters":[{"schema":{"type":"string","enum":["mod","map","version"]},"in":"query","name":"type","required":true}],"security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/upload/mod":{"post":{"summary":"上传模组","tags":["upload"],"description":"需要 x-api-key。文件先收完再返回 202，随后在后台写入源站并自动追加索引。用返回的 taskId 轮询 GET /api/v1/tasks/{taskId} 看进度。","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/upload/map":{"post":{"summary":"上传地图","tags":["upload"],"description":"需要 x-api-key。文件先收完再返回 202，随后在后台写入源站并自动追加索引。用返回的 taskId 轮询 GET /api/v1/tasks/{taskId} 看进度。","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/upload/version":{"post":{"summary":"上传游戏版本","tags":["upload"],"description":"需要 x-api-key。文件先收完再返回 202，随后在后台写入源站并自动追加索引。用返回的 taskId 轮询 GET /api/v1/tasks/{taskId} 看进度。","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/tasks/{id}":{"get":{"summary":"查询上传任务状态","tags":["upload"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/sync":{"get":{"summary":"上游同步状态","tags":["meta"],"description":"返回上次同步的时间、各类资源的增量统计。定时任务默认每小时跑一次。","responses":{"200":{"description":"Default Response"}}}},"/api/v1/sync/run":{"post":{"summary":"立即执行一轮上游同步","tags":["upload"],"description":"需要 x-api-key。拉取上游索引、补齐缺失的资源并推送到源站。\n\n默认全量（等价 `full=1`）：补资源 + 补封面 + 本体体检，且不限文件数。\n\n- `?dryRun=1` 只比对不下载\n- `?full=0` 只补资源，跳过封面与本体体检\n- `?maxFiles=N` 限制本轮最多处理几个文件（默认 0 = 不限）","parameters":[{"schema":{"type":"string","enum":["0","1"]},"in":"query","name":"dryRun","required":false},{"schema":{"type":"string","enum":["0","1"]},"in":"query","name":"full","required":false},{"schema":{"type":"integer","minimum":0,"maximum":10000},"in":"query","name":"maxFiles","required":false}],"security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://apigtl.tidewhisperai.xyz","description":"当前访问地址"}],"tags":[{"name":"catalog","description":"索引查询（公开）"},{"name":"download","description":"文件下载（公开）"},{"name":"upload","description":"上传与任务查询（上传需要 API Key）"},{"name":"meta","description":"服务信息"}]}