basePath: / info: contact: name: Luxsin description: 耳机音频参数 EQ 后端服务 title: App Audio API version: "1.0" paths: /api/v1/health: get: produces: - application/json responses: "200": description: OK schema: type: object summary: 健康检查 tags: - System /audio/getBrand: get: parameters: - description: 品牌名称（模糊匹配） in: query name: brandName type: string - description: 是否返回 base64 编码响应 in: query name: base64Resp type: string produces: - application/json responses: "200": description: OK schema: items: type: object type: array "500": description: Internal Server Error schema: type: object summary: 获取品牌列表 tags: - Brand /audio/getCurve: get: description: 根据机型和目标曲线名称，计算并返回 parametric_eq 数据 parameters: - description: 品牌名称 in: query name: brand required: true type: string - description: 型号名称 in: query name: name required: true type: string - description: 目标曲线名称 in: query name: target required: true type: string - description: 是否返回 base64 编码响应 in: query name: base64Resp type: string produces: - application/json responses: "200": description: 成功返回 parametric_eq 数据 schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: Internal Server Error schema: type: object summary: 获取目标曲线参数化 EQ tags: - Curve /audio/getModel: get: parameters: - description: 品牌名称 in: query name: brandName type: string - description: 型号名称 in: query name: modelName type: string - description: 是否返回 base64 编码响应 in: query name: base64Resp type: string produces: - application/json responses: "200": description: OK schema: items: type: object type: array "500": description: Internal Server Error schema: type: object summary: 获取型号列表 tags: - Model /audio/getModelCSV: get: description: 从 S3 读取指定机型的测量 CSV 数据，返回 frequency 和 raw 数组 parameters: - description: 品牌名称 in: query name: brand required: true type: string - description: 型号名称 in: query name: model required: true type: string - description: 耳机类型 (in-ear/over-ear) in: query name: form required: true type: string - description: 是否返回 base64 编码响应 in: query name: base64Resp type: string produces: - application/json responses: "200": description: 成功返回 frequency 和 raw 数组 schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: Internal Server Error schema: type: object summary: 获取耳机原始频响 CSV 数据 tags: - Curve /audio/modelCurve: get: description: 返回指定机型的频响曲线数据（fr），固定使用 Harman over-ear 2018 target parameters: - description: 品牌名称 in: query name: brand required: true type: string - description: 型号名称 in: query name: name required: true type: string - description: 是否返回 base64 编码响应 in: query name: base64Resp type: string produces: - application/json responses: "200": description: 成功返回 fr 数据 schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: Internal Server Error schema: type: object summary: 获取机型默认频响曲线 tags: - Curve /audio/modelList: get: parameters: - description: 搜索关键词 in: query name: key type: string - description: 返回数量上限 in: query name: count type: integer - description: 是否返回 base64 编码响应 in: query name: base64Resp type: string produces: - application/json responses: "200": description: OK schema: items: type: string type: array "500": description: Internal Server Error schema: type: object summary: 搜索型号列表（基于 Meilisearch） tags: - Model /audio/ota: get: description: 根据设备型号和硬件版本查询最新 OTA 记录，支持黑名单过滤和定向升级逻辑 parameters: - description: 设备型号 in: query name: model required: true type: string - description: 硬件版本 in: query name: hw required: true type: integer - description: 设备 MAC 地址 in: query name: mac type: string - description: 是否 beta 通道 (0=否,1=是) in: query name: beta type: integer produces: - application/json responses: "200": description: 成功返回 OTA 信息 schema: type: object "400": description: Bad Request schema: type: object "500": description: Internal Server Error schema: type: object summary: 获取 OTA 升级信息 tags: - OTA /audio/reportDevInfo: get: parameters: - description: 设备 MAC 地址 in: query name: mac required: true type: string - description: 设备型号 in: query name: model required: true type: string - description: 固件版本号 in: query name: ver type: string produces: - application/json responses: "200": description: 操作成功 schema: additionalProperties: true type: object "500": description: Internal Server Error schema: type: object summary: 上报设备信息 tags: - Device /audio/reportImpedance: get: parameters: - description: 设备 MAC 地址 in: query name: mac required: true type: string - description: 设备型号 in: query name: name required: true type: string - description: 耳机品牌 in: query name: brand required: true type: string - description: 耳机型号 in: query name: model required: true type: string - description: 阻抗值（整数） in: query name: value required: true type: integer produces: - application/json responses: "200": description: 操作成功 schema: additionalProperties: true type: object "500": description: Internal Server Error schema: type: object summary: 上报耳机阻抗 tags: - Device /audio/shareAccept: get: description: 根据分享码获取他人分享的 EQ 数据 parameters: - description: 设备 MAC 地址 in: query name: mac required: true type: string - description: 操作设备型号，取值 Luxsin-X9 或 Luxsin-X8 in: query name: model required: true type: string - description: 5 位分享码 in: query name: shareCode required: true type: string produces: - application/json responses: "200": description: 成功返回 eq_data、model schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: 系统错误 schema: additionalProperties: true type: object summary: 导入 EQ 分享码 tags: - ShareCode /audio/shareCreate: post: consumes: - application/json description: 将用户的 EQ 数据生成一个 5 位分享码，有效期由 SHARE_CODE_TTL_MIN 配置决定（支持 30、30m、24h、30d 等格式） parameters: - description: 分享请求，model 取值 Luxsin-X9 或 Luxsin-X8 in: body name: body required: true schema: properties: eq_data: type: object mac: type: string model: type: string type: object produces: - application/json responses: "200": description: 成功返回 share_code、expire_at、eq_data schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: 系统错误 schema: additionalProperties: true type: object summary: 创建 EQ 分享码 tags: - ShareCode /audio/shareDelete: get: description: 根据 MAC 与分享码删除 Redis 中的分享码数据（仅创建者可删除） parameters: - description: 设备 MAC 地址 in: query name: mac required: true type: string - description: 5 位分享码 in: query name: shareCode required: true type: string produces: - application/json responses: "200": description: 删除成功 schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: 系统错误 schema: additionalProperties: true type: object summary: 删除 EQ 分享码 tags: - ShareCode /audio/shareList: get: description: 根据设备 MAC 地址查询该设备尚未过期的所有分享码（仅查询 Redis，依赖 TTL 自动过期） parameters: - description: 设备 MAC 地址 in: query name: mac required: true type: string produces: - application/json responses: "200": description: 成功返回 share_codes 列表 schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: 系统错误 schema: additionalProperties: true type: object summary: 查询未过期分享码 tags: - ShareCode /audio/shareQuery: get: description: 根据分享码预览 EQ 数据，不写入导入流水 parameters: - description: 5 位分享码 in: query name: shareCode required: true type: string produces: - application/json responses: "200": description: 成功返回 eq_data、expire_at、model schema: additionalProperties: true type: object "400": description: 参数校验失败 schema: additionalProperties: true type: object "500": description: 系统错误 schema: additionalProperties: true type: object summary: 查询 EQ 分享码 tags: - ShareCode swagger: "2.0"