{ "openapi": "3.0.3", "info": { "title": "声音巴士开放 API v1", "version": "1.0", "description": "面向音频分享客户端的兼容 API。除明确列出的 HTTP 错误外，历史业务失败可能返回 HTTP 200，并通过 code/data 表达。请求体限制：普通 API 的完整请求体上限为 1 MiB；节目创建与更新的完整请求体上限为 110 MiB，其中音频 upload_file 单文件上限为 100 MiB。" }, "x-vbus-body-token-auth": "Authentication precedence is Cookie token > explicitly supplied Authorization header > POST body token. An explicit Cookie header value, including an empty token, suppresses lower-priority fallback. Any explicitly supplied Authorization header suppresses body-token fallback; it authenticates only when it contains one valid Bearer token, otherwise it fails closed as guest. The body token is read only from parsed JSON, urlencoded, or multipart POST bodies on /api/v1 and its child paths.", "paths": { "/api/v1": { "get": { "operationId": "getApiV1Discovery", "summary": "发现 API v1 与机器可读合同", "description": "不访问数据库；/api/v1 与 /api/v1/ 等价。", "x-vbus-auth": "none", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [], "parameters": [], "responses": { "200": { "$ref": "#/components/responses/RootDiscovery" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/program/list": { "get": { "operationId": "listPrograms", "summary": "节目列表", "description": "返回 page/pagesize/limit/total/programs；type=review 动态要求版主身份。", "x-vbus-auth": "optional-review-moderator", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "hot", "recommend", "review" ], "default": "new" }, "description": "review 需要登录且 group_id >= 200。" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true, "x-vbus-review-mode-auth": "login and group_id >= 200" } }, "/api/v1/program/item": { "get": { "operationId": "getProgram", "summary": "节目详情", "description": "GET 对普通数据库节目增加 play_count；HEAD 不增加。不可见或不存在的节目常以 HTTP 200/code=0 表达。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProgramId" }, { "name": "comment_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 }, "description": "默认最后一页，评论页固定 20 条；超过末页返回 400。" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramItemResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true, "x-vbus-get-side-effect": "increments play_count" } }, "/api/v1/program/create": { "post": { "operationId": "createProgram", "summary": "上传并创建节目", "description": "仅接收 upload_file，不接收旧 stag[]；字段类型或 album_id 非正整数返回 400。单文件上限 100 MiB，支持 MP3/M4A/OGG/WAV/FLAC。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramCreateInput" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/ProgramWrite" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "413": { "$ref": "#/components/responses/413" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/program/update": { "post": { "operationId": "updateProgram", "summary": "更新本人节目", "description": "program_id 必须位于请求体。album_id=0、content=''、tag='' 或相应字段省略时均保留旧值；upload_file 可省略，且无文件更新不会触发媒体存储。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramUpdateMultipartInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramUpdateInput" } ] } }, "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramUpdateInput" } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/ProgramWrite" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "413": { "$ref": "#/components/responses/413" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/program/recommend": { "post": { "operationId": "toggleProgramRecommendation", "summary": "设置或切换节目推荐", "description": "active 可显式设置推荐状态以安全重试；省略时保持旧客户端的切换行为。请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "moderator", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramIdActionInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramIdActionInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/ProgramIdActionInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-vbus-role": "moderator" } }, "/api/v1/program/attitude": { "post": { "operationId": "setProgramAttitude", "summary": "点赞或取消点赞", "description": "请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/RelationshipInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/RelationshipInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/RelationshipInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "description": "data 为兼容计数；active/count 为明确状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipMutation" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/program/collection": { "post": { "operationId": "setProgramCollection", "summary": "收藏或取消收藏", "description": "请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/RelationshipInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/RelationshipInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/RelationshipInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "description": "data 为兼容计数；active/count 为明确状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipMutation" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/comment/list": { "get": { "operationId": "listComments", "summary": "节目评论列表", "description": "返回 page/pagesize/limit/total/comments。普通用户只见 status=0 评论且父节目必须为 status=0；版主可查看隐藏父节目的评论。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProgramId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/comment/item": { "get": { "operationId": "getComment", "summary": "评论详情", "description": "普通用户只见 status=0 评论，且父节目必须为 status=0；版主保留审核访问。不存在或隐藏通常以 HTTP 200/code=0 表达。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CommentId" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentItemResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/comment/create": { "post": { "operationId": "createComment", "summary": "发表评论", "description": "成功 data='ok'；普通用户只能评论 status=0 的父节目，版主保留审核评论能力。输入类型错误为 400，空内容、内容词或节目不存在通常为 HTTP 200/code=0。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/CommentCreateInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/CommentCreateInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/CommentCreateInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/comment/shield": { "post": { "operationId": "toggleCommentShield", "summary": "切换评论屏蔽", "description": "请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "moderator", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/CommentShieldInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/CommentShieldInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/CommentShieldInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-role": "moderator" } }, "/api/v1/tag/list": { "get": { "operationId": "listTags", "summary": "标签列表", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "default": "new" }, "description": "recommend 过滤推荐；其他未知字符串兼容为按 program_count 排序，非字符串返回 400。" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/tag/item": { "get": { "operationId": "getTag", "summary": "标签详情", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TagId" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagItemResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/tag/program": { "get": { "operationId": "listTagPrograms", "summary": "标签下的节目", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TagId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagProgramsResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/tag/hot": { "get": { "operationId": "listHotTags", "summary": "热门标签", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize10" }, { "$ref": "#/components/parameters/Limit10" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/tag/recommend": { "post": { "operationId": "toggleTagRecommendation", "summary": "设置或切换标签推荐", "description": "active 可显式设置推荐状态以安全重试；省略时保持旧客户端的切换行为。请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "moderator", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/TagIdActionInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/TagIdActionInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/TagIdActionInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-vbus-role": "moderator" } }, "/api/v1/album/list": { "get": { "operationId": "listAlbums", "summary": "专辑列表", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "default": "new" }, "description": "recommend 过滤推荐；其他非 new 字符串兼容为按 attitude_count 排序，非字符串返回 400。" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/album/item": { "get": { "operationId": "getAlbum", "summary": "专辑详情", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AlbumId" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumItemResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/album/program": { "get": { "operationId": "listAlbumPrograms", "summary": "专辑下的节目", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AlbumId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumProgramsResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/album/recommend": { "get": { "operationId": "listRecommendedAlbums", "summary": "推荐专辑列表", "description": "成功与业务失败均沿用 {code,data} 兼容信封；部分业务失败返回 HTTP 200 且 code 不为 1。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize10" }, { "$ref": "#/components/parameters/Limit10" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true }, "post": { "operationId": "toggleAlbumRecommendation", "summary": "设置或切换专辑推荐", "description": "active 可显式设置推荐状态以安全重试；省略时保持旧客户端的切换行为。请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "moderator", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumIdActionInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumIdActionInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumIdActionInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-vbus-role": "moderator" } }, "/api/v1/album/create": { "post": { "operationId": "createAlbum", "summary": "创建专辑", "description": "请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumCreateInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumCreateInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumCreateInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "description": "结构化创建结果、旧 HTML option 或兼容业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumCreateResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/album/update": { "post": { "operationId": "updateAlbum", "summary": "更新本人专辑", "description": "album_id 与非空 album_name 必填；album_description 省略或空字符串时保留旧描述。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumUpdateInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumUpdateInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumUpdateInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/album/delete": { "post": { "operationId": "deleteAlbum", "summary": "删除本人专辑", "description": "只有 confirm=true、1 或字符串 '1' 才执行删除；省略或 false 返回 HTTP 200/code=0 且不删除，其他值返回 400。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumDeleteInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumDeleteInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/AlbumDeleteInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/user/recommend": { "get": { "operationId": "listRecommendedUsers", "summary": "用户推荐列表", "description": "兼容名称；实际按 program_count 返回用户，不按 recommend 字段过滤。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize10" }, { "$ref": "#/components/parameters/Limit10" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true }, "post": { "operationId": "toggleUserRecommendation", "summary": "设置或切换用户推荐", "description": "active 可显式设置推荐状态以安全重试；省略时保持旧客户端的切换行为。请求体 token 是旧客户端兼容字段；业务失败可能保持 HTTP 200 并通过 code/data 表达。", "x-vbus-auth": "moderator", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/UserIdActionInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/UserIdActionInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/UserIdActionInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "x-vbus-role": "moderator" } }, "/api/v1/user/profile": { "get": { "operationId": "getUserProfile", "summary": "用户资料", "description": "公开字段始终可见；本人或 group_id>=210 可额外看到受限账户字段。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true, "x-vbus-conditional-private-fields": [ "email", "mobile", "credit1", "credit2", "credit3", "online_time", "login_count", "pm_count", "login_time", "created_ip", "login_ip" ] } }, "/api/v1/user/album": { "get": { "operationId": "listUserAlbums", "summary": "用户专辑", "description": "返回 viewer 相关用户资料与公开 status=0 资源。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAlbumsResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/user/collection": { "get": { "operationId": "listUserCollections", "summary": "用户收藏", "description": "返回 viewer 相关用户资料与公开 status=0 资源。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProgramsResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/user/attitude": { "get": { "operationId": "listUserAttitudes", "summary": "用户点赞", "description": "返回 viewer 相关用户资料与公开 status=0 资源。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProgramsResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/user/program": { "get": { "operationId": "listUserPrograms", "summary": "用户节目", "description": "返回 viewer 相关用户资料与公开 status=0 资源。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProgramsResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/user/login": { "post": { "operationId": "loginUser", "summary": "开放 API 登录", "description": "成功返回 uid/username/group_id/token，不设置 Cookie；错误凭据通常 HTTP 200/code=0。", "x-vbus-auth": "none", "x-vbus-body-token-auth": true, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/LoginInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/LoginInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/LoginInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/Login" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/search": { "get": { "operationId": "search", "summary": "搜索节目、标签、专辑或用户", "description": "始终返回 programs/users/tags/albums 四个数组，仅所选 type 被填充。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "default": "" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "program", "tag", "album", "user" ], "default": "program" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/article/list": { "get": { "operationId": "listArticles", "summary": "文章列表", "description": "仅返回 status=0 的数据库文章；new 按 article_id，hot 按 view_count。expired 为未启用的兼容字段，当前不参与可见性判断。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "hot" ], "default": "new" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true } }, "/api/v1/article/item": { "get": { "operationId": "getArticle", "summary": "文章详情", "description": "article_id 可为正整数或安全 slug；数据库文章仅返回 status=0，内置政策文章不受数据库状态影响。普通数据库文章 GET 增加 view_count；HEAD 与内置政策文章不增加。", "x-vbus-auth": "optional", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ {}, { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ArticleId" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleItemResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-public-read": true, "x-vbus-get-side-effect": "increments view_count" } }, "/api/v1/check/username": { "post": { "operationId": "checkUsername", "summary": "检查用户名可用性", "description": "兼容可用性接口；非字符串字段返回 400。code=0/data=true 常表示可用，规则或占用结果并不统一使用 HTTP 4xx。", "x-vbus-auth": "none", "x-vbus-body-token-auth": true, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/UsernameCheckInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/UsernameCheckInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/UsernameCheckInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/check/email": { "post": { "operationId": "checkEmail", "summary": "检查邮箱可用性", "description": "兼容可用性接口；非字符串字段返回 400。code=0/data=true 常表示可用，规则或占用结果并不统一使用 HTTP 4xx。", "x-vbus-auth": "none", "x-vbus-body-token-auth": true, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/EmailCheckInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/EmailCheckInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/EmailCheckInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/check/mobile": { "post": { "operationId": "checkMobile", "summary": "检查手机号可用性", "description": "兼容可用性接口；非字符串字段返回 400。code=0/data=true 常表示可用，规则或占用结果并不统一使用 HTTP 4xx。", "x-vbus-auth": "none", "x-vbus-body-token-auth": true, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/MobileCheckInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/MobileCheckInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/MobileCheckInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } }, "/api/v1/check/hash": { "post": { "operationId": "checkFileHash", "summary": "检查音频 SHA-1 是否已存在", "description": "file_hash 必须为 40 位十六进制；存在 code=1/data=true，不存在 code=0/data=false。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/HashCheckInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/HashCheckInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/HashCheckInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/pm/list": { "get": { "operationId": "listPrivateMessagePeers", "summary": "私信会话列表", "description": "仅返回安全会话对端字段；GET type=to 清零 pm_count，HEAD 不清零。", "x-vbus-auth": "login", "x-vbus-head": { "body": "empty", "side_effects": "none", "preserves": "status, Content-Type, deterministic Content-Length" }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "to", "from" ], "default": "to" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize20" }, { "$ref": "#/components/parameters/Limit20" } ], "responses": { "200": { "description": "结构化成功数据或兼容 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PmListResult" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" } }, "x-vbus-get-side-effect": "type=to clears unread count" } }, "/api/v1/pm/create": { "post": { "operationId": "createPrivateMessage", "summary": "发送私信", "description": "成功 data='发送成功。'，不返回 pm_id；部分业务失败保持 HTTP 200/code=0。", "x-vbus-auth": "login", "x-vbus-body-token-auth": true, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/PmCreateInput" } ] } }, "application/x-www-form-urlencoded": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/PmCreateInput" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BodyToken" }, { "$ref": "#/components/schemas/PmCreateInput" } ] } } } }, "responses": { "413": { "$ref": "#/components/responses/413" }, "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "405": { "$ref": "#/components/responses/405" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } } } } }, "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "token", "description": "浏览器兼容 token Cookie；写请求仍受同源与 CSRF 策略约束。" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque v1 token", "description": "原生或服务端客户端推荐方式。" } }, "parameters": { "Page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, "PageSize20": { "name": "pagesize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "limit 与 pagesize 是等价别名；若同时提供，数值必须相同，否则返回 400。" }, "Limit20": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "limit 与 pagesize 是等价别名；若同时提供，数值必须相同，否则返回 400。" }, "PageSize10": { "name": "pagesize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "limit 与 pagesize 是等价别名；若同时提供，数值必须相同，否则返回 400。" }, "Limit10": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "limit 与 pagesize 是等价别名；若同时提供，数值必须相同，否则返回 400。" }, "ProgramId": { "name": "program_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "CommentId": { "name": "comment_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "TagId": { "name": "tag_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "AlbumId": { "name": "album_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "UserId": { "name": "uid", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "ArticleId": { "name": "article_id", "in": "query", "required": true, "schema": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)(?![0-9]+$)[^\\x00-\\x1F\\x7F]+$", "description": "非纯数字、无首尾空白且不含 ASCII 控制字符的 slug。" } ] } } }, "responses": { "200": { "description": "兼容成功或业务结果信封。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityResult" } } } }, "400": { "description": "输入格式或分页边界错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "需要登录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "权限或同源策略拒绝。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "资源或接口不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "请求方法不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Allow": { "schema": { "type": "string" }, "description": "该路径支持的方法。" } } }, "413": { "description": "请求体超过当前接口限制；普通 API 完整请求体上限为 1 MiB，节目创建/更新完整请求体上限为 110 MiB，其中音频 upload_file 单文件另限 100 MiB。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "音频格式、内容或事务约束无法处理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "请求过于频繁或同一用户已有上传在处理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "500": { "description": "未捕获异常；固定 JSON，不暴露内部细节。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "依赖服务或持久化暂时不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RootDiscovery": { "description": "固定、无数据库发现响应；HEAD body 为空并保留确定长度。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootDiscovery" } } } }, "ProgramWrite": { "description": "节目写入成功或历史 HTTP 200 业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramWriteResult" } } } }, "Login": { "description": "登录成功或兼容业务失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResult" } } } } }, "schemas": { "BodyToken": { "type": "object", "properties": { "token": { "type": "string", "description": "POST 兼容凭据；优先级低于 Cookie 与 Bearer。" }, "form_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Cookie 登录写请求可提交的 CSRF token；也可使用 X-CSRF-Token 请求头或可信同源 AJAX 证据。" } } }, "LegacyInteger": { "description": "旧数据库资源的非负整数；历史 PDO JSON 输出通常为十进制字符串，部分应用生成值为原生整数。", "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ] }, "NullableLegacyInteger": { "description": "可为 null 的旧数据库非负整数资源。", "nullable": true, "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pagesize": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } }, "Program": { "type": "object", "properties": { "program_id": { "$ref": "#/components/schemas/LegacyInteger" }, "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "username": { "type": "string" }, "program_name": { "type": "string" }, "file_hash": { "type": "string" }, "play_count": { "$ref": "#/components/schemas/LegacyInteger" }, "external_play_count": { "$ref": "#/components/schemas/LegacyInteger" }, "comment_count": { "$ref": "#/components/schemas/LegacyInteger" }, "attitude_count": { "$ref": "#/components/schemas/LegacyInteger" }, "collection_count": { "$ref": "#/components/schemas/LegacyInteger" }, "file_path": { "type": "string" }, "third_party_url": { "type": "string" }, "content": { "type": "string", "nullable": true }, "created": { "type": "string" }, "modified": { "type": "string" }, "status": { "$ref": "#/components/schemas/LegacyInteger" }, "review": { "$ref": "#/components/schemas/LegacyInteger" }, "report": { "$ref": "#/components/schemas/LegacyInteger" }, "recommend": { "$ref": "#/components/schemas/LegacyInteger" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "albums": { "type": "array", "items": { "$ref": "#/components/schemas/Album" } }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "review_logs": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewLog" } }, "comment_page": { "type": "integer" }, "comment_pagesize": { "type": "integer" }, "comment_total": { "type": "integer" }, "attitude_pressed": { "type": "boolean" }, "collection_pressed": { "type": "boolean" } } }, "Album": { "type": "object", "properties": { "album_id": { "$ref": "#/components/schemas/LegacyInteger" }, "album_name": { "type": "string" }, "album_description": { "type": "string", "nullable": true }, "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "program_count": { "$ref": "#/components/schemas/LegacyInteger" }, "attitude_count": { "$ref": "#/components/schemas/LegacyInteger" }, "order": { "$ref": "#/components/schemas/LegacyInteger" }, "status": { "$ref": "#/components/schemas/LegacyInteger" }, "recommend": { "$ref": "#/components/schemas/LegacyInteger" } } }, "Tag": { "type": "object", "properties": { "tag_id": { "$ref": "#/components/schemas/LegacyInteger" }, "tag_name": { "type": "string" }, "slug": { "type": "string" }, "tag_description": { "type": "string", "nullable": true }, "program_count": { "$ref": "#/components/schemas/LegacyInteger" }, "attitude_count": { "$ref": "#/components/schemas/LegacyInteger" }, "order": { "$ref": "#/components/schemas/LegacyInteger" }, "status": { "$ref": "#/components/schemas/LegacyInteger" }, "recommend": { "$ref": "#/components/schemas/LegacyInteger" }, "parent": { "$ref": "#/components/schemas/NullableLegacyInteger" } } }, "Article": { "type": "object", "properties": { "article_id": { "$ref": "#/components/schemas/LegacyInteger" }, "title": { "type": "string" }, "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "username": { "type": "string" }, "slug": { "type": "string" }, "created": { "type": "string" }, "modified": { "type": "string" }, "expired": { "type": "string" }, "category_id": { "$ref": "#/components/schemas/LegacyInteger" }, "view_count": { "$ref": "#/components/schemas/LegacyInteger" }, "status": { "$ref": "#/components/schemas/LegacyInteger" }, "order": { "$ref": "#/components/schemas/LegacyInteger" }, "text": { "type": "string", "nullable": true }, "version": { "type": "string" }, "effective_date": { "type": "string" }, "updated_note": { "type": "string" } } }, "ReviewLog": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/LegacyInteger" }, "program_id": { "$ref": "#/components/schemas/LegacyInteger" }, "status": { "$ref": "#/components/schemas/LegacyInteger" }, "created": { "type": "string" }, "modified": { "type": "string" }, "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "username": { "type": "string" }, "comment": { "type": "string" } } }, "PublicUser": { "type": "object", "properties": { "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "username": { "type": "string" }, "group_id": { "$ref": "#/components/schemas/LegacyInteger" }, "program_count": { "$ref": "#/components/schemas/LegacyInteger" }, "album_count": { "$ref": "#/components/schemas/LegacyInteger" }, "recommend": { "$ref": "#/components/schemas/LegacyInteger" }, "created": { "type": "string" } } }, "Comment": { "type": "object", "properties": { "comment_id": { "$ref": "#/components/schemas/LegacyInteger" }, "program_id": { "$ref": "#/components/schemas/LegacyInteger" }, "created": { "type": "string" }, "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "owner_id": { "$ref": "#/components/schemas/LegacyInteger" }, "username": { "type": "string" }, "text": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/LegacyInteger" }, "parent": { "$ref": "#/components/schemas/NullableLegacyInteger" } } }, "PmUser": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/LegacyInteger" }, "modified": { "type": "string" }, "uid": { "$ref": "#/components/schemas/LegacyInteger" }, "username": { "type": "string" }, "program_count": { "$ref": "#/components/schemas/LegacyInteger" }, "album_count": { "$ref": "#/components/schemas/LegacyInteger" } } }, "UserProfile": { "allOf": [ { "$ref": "#/components/schemas/PublicUser" }, { "type": "object", "properties": { "group_name": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "credit1": { "$ref": "#/components/schemas/LegacyInteger" }, "credit2": { "$ref": "#/components/schemas/LegacyInteger" }, "credit3": { "$ref": "#/components/schemas/LegacyInteger" }, "online_time": { "$ref": "#/components/schemas/LegacyInteger" }, "login_count": { "$ref": "#/components/schemas/LegacyInteger" }, "pm_count": { "$ref": "#/components/schemas/LegacyInteger" }, "login_time": { "type": "string" }, "created_ip": { "type": "string" }, "login_ip": { "type": "string" } } } ], "description": "group_name 可公开；其余附加字段仅本人或 group_id>=210 可见。" }, "RelationshipMutation": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "integer", "description": "旧客户端兼容计数。" }, "active": { "type": "boolean" }, "count": { "type": "integer" } }, "required": [ "code", "data", "active", "count" ] }, "SuccessEnvelope": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "description": "端点特定的兼容成功数据。" } }, "required": [ "code", "data" ] }, "ErrorEnvelope": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "description": "固定错误信息或端点特定错误数据。" }, "errors": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "code", "data" ] }, "RootDiscovery": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "properties": { "version": { "type": "string", "enum": [ "1.0" ] }, "documentation": { "type": "string", "enum": [ "/article/api" ] }, "openapi": { "type": "string", "enum": [ "/openapi-v1.yaml" ] } }, "required": [ "version", "documentation", "openapi" ] } }, "required": [ "code", "data" ] }, "ProgramWriteEnvelope": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "object", "properties": { "program_id": { "type": "integer" } }, "required": [ "program_id" ] } }, "required": [ "code", "data" ] }, "AlbumCreateEnvelope": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "data": { "type": "string", "description": "旧客户端使用的 HTML