openapi: 3.0.3
info:
  title: '轻语开放平台 · 开发对接文档'
  description: "接口说明、调用示例与本地在线调试。\n\n## 开发指南\n\n从接入到支付，按调用顺序了解接口之间的关系。图中实线表示主流程，虚线表示可选步骤或异步处理；接口详情中可查看参数并发起测试。\n\n[接入流程](#description/01-接入流程) · [公司预充值](#description/02-支付流程公司预充值) · [小程序支付](#description/03-小程序支付流程)\n\n点击图表右上角「展开阅读」可查看完整大图，支持缩放、拖动；按 Esc 返回文档。\n\n### 01 · 接入流程\n\n**先建立用户与设备关系，再选择资源、应用智能体。** 凭证与 Token 由接入方服务端管理。\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"look\":\"classic\",\"themeVariables\":{\"primaryColor\":\"#f1f5ff\",\"primaryTextColor\":\"#253858\",\"primaryBorderColor\":\"#b4c4ed\",\"lineColor\":\"#8794aa\",\"fontFamily\":\"system-ui, sans-serif\",\"fontSize\":\"14px\"},\"flowchart\":{\"wrappingWidth\":420,\"curve\":\"basis\",\"nodeSpacing\":24,\"rankSpacing\":32}}}%%\nflowchart TB\n    A(\"01 获取 Token<br/>POST /openapi/auth/token\") -->|Bearer Token| B(\"02 注册用户<br/>PUT /openapi/user/register\")\n    B -->|沿用提交的 account| C{\"03 选择设备绑定方式\"}\n    C --> D(\"MAC 绑定<br/>PUT /openapi/mac/user\")\n    C --> E(\"配对码绑定<br/>POST /openapi/device/code/bind\")\n    D --> F(\"04 选择智能体与配置\")\n    E --> F\n    F -. 按需查询 .-> G(\"模型 · 智能体 · 音色<br/>GET /openapi/get/model/list<br/>POST /openapi/user/works/list<br/>GET /openapi/timbre/list\")\n    F --> H(\"05 应用到设备<br/>PATCH /openapi/work/bind-to-device<br/>或 PATCH /openapi/work/bind-to-devices\")\n    G -.-> H\n    H --> I(\"06 设备端使用 / 开始对话\")\n    classDef done fill:#edf9f3,stroke:#92c7ac,color:#215b3d;\n    class I done;\n```\n\n- **账号衔接**：注册成功不会返回新的 `user_account`，后续使用注册时提交的外部 `account`；需要查询时使用用户信息接口。\n- **应用范围**：`bind-to-device` 面向该用户的设备；`bind-to-devices` 通过设备 ID 选择目标，详见参数说明。\n- **完成条件**：应用接口成功表示服务端配置成功，设备实际生效还取决于设备连接与同步；“开始对话”为设备端行为。\n\n**相关接口**：[POST /openapi/auth/token](#tag/01-%E6%8E%A5%E5%85%A5%E9%89%B4%E6%9D%83/POST/openapi/auth/token) · [PUT /openapi/user/register](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/PUT/openapi/user/register) · [POST /openapi/user/info](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/POST/openapi/user/info) · [PUT /openapi/mac/user](#tag/04-%E8%AE%BE%E5%A4%87%E4%B8%8E%E7%BB%91%E5%AE%9A/PUT/openapi/mac/user) · [POST /openapi/device/code/bind](#tag/08-%E8%AE%BE%E5%A4%87%E4%BA%8B%E4%BB%B6/POST/openapi/device/code/bind) · [PATCH /openapi/work/bind-to-device](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/PATCH/openapi/work/bind-to-device) · [PATCH /openapi/work/bind-to-devices](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/PATCH/openapi/work/bind-to-devices)\n\n### 02 · 支付流程（公司预充值）\n\n**先联系商务充值，再由接口扣减公司余额。** 普通权益购买后开通；音色克隆购买后还需要提交录音并等待训练。\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"look\":\"classic\",\"themeVariables\":{\"primaryColor\":\"#f1f5ff\",\"primaryTextColor\":\"#253858\",\"primaryBorderColor\":\"#b4c4ed\",\"lineColor\":\"#8794aa\",\"fontFamily\":\"system-ui, sans-serif\",\"fontSize\":\"14px\"},\"flowchart\":{\"wrappingWidth\":420,\"curve\":\"basis\",\"nodeSpacing\":24,\"rankSpacing\":36}}}%%\nflowchart TB\n    A(\"01 联系商务 · 公司预充值\") --> B{\"02 选择购买类型\"}\n    B -. 查询余额 .-> Q(\"GET /openapi/corporation/balance/log<br/>type = 0\")\n    subgraph RIGHTS[普通权益 · 会员 / 音色 / 音乐]\n        C(\"查询卡片列表<br/>GET /openapi/membership/cardList<br/>GET /openapi/timbre/cardList<br/>GET /openapi/music/cardList\") --> D(\"03 余额扣费购买<br/>PUT /openapi/user/musicians/pay\")\n        D -->|购买成功| E(\"04 权益开通 · 查询到期时间<br/>GET /openapi/musicians/expiretime\")\n    end\n    subgraph CLONE[音色克隆 · 购买名额后提交训练]\n        F(\"查询克隆商品<br/>GET /openapi/clone/my-timbre/pay/list\") --> G(\"03 余额扣费购买<br/>POST /openapi/clone/my-timbre/pay/corporation_buy\")\n        G -->|购买成功| H(\"04 查询名额 · 取得 pay_id<br/>GET /openapi/clone/my-timbre/list\")\n        H --> I(\"05 提交录音<br/>POST /openapi/clone/my-timbre\")\n        I -. 等待异步训练 .-> J(\"06 查询列表取得 id · 查询审核结果<br/>GET /openapi/clone/my-timbre/check-status\")\n        J -->|训练成功| K(\"应用克隆音色\")\n        J -->|失败| L(\"重新提交录音<br/>POST /openapi/clone/my-timbre/re-audit\")\n        L -. 等待后再次查询 .-> J\n    end\n    B --> C\n    B --> F\n    D -. 核对扣费 .-> M(\"查询公司扣减记录<br/>GET /openapi/corporation/balance/log<br/>type = 1\")\n    G -. 核对扣费 .-> M\n    classDef done fill:#edf9f3,stroke:#92c7ac,color:#215b3d;\n    classDef wait fill:#fff8e8,stroke:#dfc57e,color:#785a19;\n    class E,K done;\n    class I,J,L wait;\n```\n\n| 场景 | 类型参数 | 后续确认 |\n| --- | --- | --- |\n| 公司余额购买 | `buy_type=1` 会员、`2` 音色、`3` 音乐 | 购买成功后查询权益 |\n| 查询到期时间 | `type=1` 会员、`2` 音乐、`3` 音色 | 注意与购买的枚举顺序不同 |\n| 音色克隆 | 先获取购买名额的 `pay_id`，再提交录音 | 训练成功后才可应用音色 |\n\n余额不足等购买失败时停止后续步骤。服务端按商品价格扣费；不要把客户端传值作为结算依据。重复购买可能再次扣费，请在业务侧避免重复提交。提交录音后通常至少等待约 305 秒再查询；读取 `timbre_state` 区分 Training、Success、Failed 等状态，训练中则稍后再查，不能仅按 `code=200` 判断完成。\n\n**相关接口**：[PUT /openapi/user/musicians/pay](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/PUT/openapi/user/musicians/pay) · [GET /openapi/musicians/expiretime](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/GET/openapi/musicians/expiretime) · [GET /openapi/corporation/balance/log](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/GET/openapi/corporation/balance/log) · [POST /openapi/clone/my-timbre/pay/corporation_buy](#tag/09-%E9%9F%B3%E8%89%B2%E5%85%8B%E9%9A%86/POST/openapi/clone/my-timbre/pay/corporation_buy) · [GET /openapi/clone/my-timbre/list](#tag/09-%E9%9F%B3%E8%89%B2%E5%85%8B%E9%9A%86/GET/openapi/clone/my-timbre/list) · [POST /openapi/clone/my-timbre](#tag/09-%E9%9F%B3%E8%89%B2%E5%85%8B%E9%9A%86/POST/openapi/clone/my-timbre) · [GET /openapi/clone/my-timbre/check-status](#tag/09-%E9%9F%B3%E8%89%B2%E5%85%8B%E9%9A%86/GET/openapi/clone/my-timbre/check-status) · [POST /openapi/clone/my-timbre/re-audit](#tag/09-%E9%9F%B3%E8%89%B2%E5%85%8B%E9%9A%86/POST/openapi/clone/my-timbre/re-audit)\n\n### 03 · 小程序支付流程\n\n**推荐使用 V2 统一下单。** 接入方服务端负责调用开放平台，小程序端使用返回的 JSAPI 参数唤起微信支付。\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"primaryColor\":\"#f1f5ff\",\"primaryTextColor\":\"#253858\",\"primaryBorderColor\":\"#b4c4ed\",\"lineColor\":\"#8794aa\",\"actorBkg\":\"#f1f5ff\",\"actorBorder\":\"#b4c4ed\",\"actorTextColor\":\"#253858\",\"signalColor\":\"#8794aa\",\"signalTextColor\":\"#253858\",\"noteBkgColor\":\"#fff8e8\",\"noteTextColor\":\"#785a19\",\"noteBorderColor\":\"#dfc57e\",\"fontFamily\":\"system-ui, sans-serif\",\"fontSize\":\"14px\"},\"sequence\":{\"mirrorActors\":false,\"useMaxWidth\":true,\"wrap\":true,\"width\":150,\"messageMargin\":34}}}%%\nsequenceDiagram\n    autonumber\n    participant Mini as 小程序端\n    participant Server as 接入方服务端\n    participant API as 轻语开放平台\n    participant WX as 微信支付\n    Mini->>Server: 选择商品 / 请求支付\n    Server->>API: 获取会员 / 音色 / 音乐卡列表\n    API-->>Server: 商品 ID 与价格\n    Server-->>Mini: 展示商品信息\n    Mini->>Server: 确认商品，提交 openid\n    Server->>API: POST /openapi/user/orders/v2/pay\n    Note over Server,API: id / type / amount / account / openid；appid 按接口约定\n    API->>WX: 创建微信预支付订单\n    WX-->>API: 预支付信息\n    API-->>Server: JSAPI 支付参数\n    Server-->>Mini: 返回 JSAPI 支付参数\n    Mini->>WX: 唤起支付，用户确认\n    alt 支付成功\n        WX-->>API: 异步支付通知\n        API->>API: 校验通知并开通权益\n        Mini->>Server: 查询权益\n        Server->>API: GET /openapi/musicians/expiretime\n        API-->>Server: 当前权益到期时间\n        Server-->>Mini: 展示权益结果\n    else 用户取消 / 支付失败\n        WX-->>Mini: 展示取消 / 失败结果\n        Note over Mini,Server: 不按下单成功开通权益\n    end\n```\n\n- **预支付不等于付款**：下单成功只代表拿到支付参数；以平台处理支付通知后的权益结果为准，通知可能晚于客户端返回。\n- **参数衔接**：V2 的 `type=1` 会员、`2` 音色、`3` 音乐、`4` 套餐。`amount` 必填，实际价格按服务端商品计算；`openid` 必须与支付使用的 `appid` 对应。\n- **查询范围**：到期时间接口查询会员、音乐、音色权益；套餐涉及的权益按实际开通内容核对。当前开放平台没有单独的通用订单状态查询接口。\n- **凭证边界**：接入凭证与 Bearer Token 保留在接入方服务端；微信异步通知由平台处理，图中没有新增接入方回调接口。\n\n**兼容旧链路**：先 [POST /openapi/user/equity/orders](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/POST/openapi/user/equity/orders) 获取 `code`，再 [POST /openapi/user/orders/pay](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/POST/openapi/user/orders/pay) 获取 JSAPI 参数；后续支付与权益确认同上。旧图中的“App 支付”不作为这两个接口的支付方式说明。\n\n**相关接口**：[POST /openapi/user/orders/v2/pay](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/POST/openapi/user/orders/v2/pay) · [GET /openapi/membership/cardList](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/GET/openapi/membership/cardList) · [GET /openapi/timbre/cardList](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/GET/openapi/timbre/cardList) · [GET /openapi/music/cardList](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/GET/openapi/music/cardList) · [GET /openapi/musicians/expiretime](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/GET/openapi/musicians/expiretime)\n\n### 04 · 第三方小程序拉起轻语小程序支付\n\n**优先使用 [03 · 小程序支付流程](#description/03-小程序支付流程) 的预支付。** 接入方服务端调用 [POST /openapi/user/orders/v2/pay](#tag/02-%E7%94%A8%E6%88%B7%E4%B8%8E%E6%9D%83%E7%9B%8A/POST/openapi/user/orders/v2/pay) 获取 JSAPI 参数，在自己的小程序内唤起微信支付。需要在轻语小程序内完成虚拟支付时，再按下面的方式拉起，拉起三方小程序支付审核可能会失败，可以在审核期间做下区分\n\n**由第三方小程序拉起轻语支付页，在轻语小程序内完成微信虚拟支付。** 用 `user_account` 定位用户。权益由轻语侧在支付通知后开通，第三方不发货。\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"primaryColor\":\"#f1f5ff\",\"primaryTextColor\":\"#253858\",\"primaryBorderColor\":\"#b4c4ed\",\"lineColor\":\"#8794aa\",\"actorBkg\":\"#f1f5ff\",\"actorBorder\":\"#b4c4ed\",\"actorTextColor\":\"#253858\",\"signalColor\":\"#8794aa\",\"signalTextColor\":\"#253858\",\"noteBkgColor\":\"#fff8e8\",\"noteTextColor\":\"#785a19\",\"noteBorderColor\":\"#dfc57e\",\"fontFamily\":\"system-ui, sans-serif\",\"fontSize\":\"14px\"},\"sequence\":{\"mirrorActors\":false,\"useMaxWidth\":true,\"wrap\":true,\"width\":150,\"messageMargin\":34}}}%%\nsequenceDiagram\n    autonumber\n    participant Third as 第三方小程序\n    participant Server as 接入方服务端\n    participant Page as 轻语支付页\n    participant API as 轻语服务端\n    participant WX as 微信虚拟支付\n    Third->>Server: 准备支付，提交 user_account\n    Server->>API: GET /api/mini-app/pay/external/user/check\n    Note over Server,API: 可选。仅在接入方服务端调用\n    API-->>Server: 账号是否存在\n    Server-->>Third: 允许拉起\n    Third->>Page: wx.navigateToMiniProgram<br/>envVersion = release\n    Note over Third,Page: 固定打开轻语正式版。path 后缀与 extraData 携带 user_account、type、商品参数、api_env\n    Page->>API: 进入页面即校验账号<br/>GET /api/mini-app/pay/external/user/check\n    API-->>Page: errorCode = 0 才允许支付\n    Page->>Page: uni.login 取得轻语小程序 wx_code\n    Page->>API: POST /api/mini-app/pay/external/xuni-pay\n    API-->>Page: signData / paySig / signature\n    Page->>WX: wx.requestVirtualPayment\n    alt 支付成功\n        WX-->>API: 异步支付通知\n        API->>API: 校验通知并开通权益\n        Page-->>Third: navigateBackMiniProgram<br/>success、order、amount、type、user_account\n    else 用户取消 / 支付失败\n        WX-->>Page: 取消或失败\n        Page-->>Third: success = false，canceled = true\n        Note over Third,API: 不按拉起成功开通权益\n    end\n```\n\n拉起示例。`envVersion` 固定为 `release`，打开轻语小程序正式版。`extraData` 覆盖 path 上的同名参数，路径上也带一份，避免小程序在后台时读不到 `extraData`。\n\n```js\nwx.navigateToMiniProgram({\n  appId: '轻语小程序 appId',\n  path: 'pages/external-pay/open-external-pay?user_account=qy123456&type=5&goods_id=12&amount=9.9&title=克隆音色&api_env=production',\n  extraData: {\n    user_account: 'qy123456',\n    type: 5,\n    goods_id: 12,\n    amount: 9.9,\n    title: '克隆音色',\n    account_name: '张三',\n    api_env: 'production'\n  },\n  envVersion: 'release'\n})\n```\n\n| type | 商品 | 拉起时必须再传 | 下单成功 |\n| --- | --- | --- | --- |\n| `1` / `2` / `3` / `4` | 积分卡、音色卡、音乐卡、套餐卡 | `key`、`amount` | `code = 200`，签名在 `data.orderStr` |\n| `5` | 克隆音色购买 | `goods_id` | `errorCode = 0`，签名在 `data` |\n| `6` | 克隆音色续期 | `goods_id`、`timbre_id` | 同 `5` |\n\n- **账号**：`user_account` 是平台账号唯一标识。页面打开后会调用账号校验；`errorCode = 0` 才可支付。拉起前的校验返回手机号，只在接入方服务端调用。\n- **小程序版本**：`envVersion` 固定传 `release`，打开轻语小程序正式版。\n- **接口环境**：`api_env=test` 走测试，`api_env=production` 走正式。只作用于账号校验和下单。安卓测试 `wx_env=1`，正式 `wx_env=0`；iOS 固定 `wx_env=0`。未传 `api_env` 时沿用轻语小程序当前环境。\n- **展示字段**：`title`、`description`、`account_name` 只用于支付页展示。`5`、`6` 的 `amount` 同样只用于展示，价格由服务端计算。\n- **结果**：预支付参数只表示可以拉起微信支付。权益以轻语侧处理支付通知后的结果为准。支付成功后页面把订单号带回第三方小程序。\n\n"
  version: 1.0.0
servers:
  -
    url: 'https://test.nihaoxiaozhi.com'
tags:
  -
    name: '01 接入鉴权'
    description: ''
  -
    name: '02 用户与权益'
    description: ''
  -
    name: '03 用户设置'
    description: ''
  -
    name: '04 设备与绑定'
    description: ''
  -
    name: '05 智能体'
    description: ''
  -
    name: '06 饮水管理'
    description: ''
  -
    name: '07 对话记录'
    description: ''
  -
    name: '08 设备事件'
    description: ''
  -
    name: '09 音色克隆'
    description: ''
  -
    name: '10 内容资源'
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: '先调用 POST /openapi/auth/token，复制响应 data 中的 Token。有效期按代码配置为 30 天；提前失效时重新获取。Token 不是 JWT，不需要自行解码。'
security:
  -
    default: []
paths:
  /openapi/auth/token:
    post:
      summary: '获取访问 Token'
      operationId: post_openapi_auth_token
      description: '使用接入方凭证获取 Token。成功时 data 为字符串，后续请求携带 Authorization: Bearer {token}。缓存有效期为 30 天，提前失效需重新获取。凭证错误为 HTTP 400；自定义参数校验失败为 HTTP 200、code=400。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data: YOUR_TOKEN
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: string
                        example: YOUR_TOKEN
                        description: '访问 Token 字符串；不是 JWT。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '参数校验失败（HTTP 200）'
                    type: object
                    example:
                      message: '请传Access Key！'
                      code: 400
                    properties:
                      message:
                        type: string
                        example: '请传Access Key！'
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: '历史错误响应：Access Key错误！'
                    type: object
                    example:
                      message: 'Access Key错误！'
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 'Access Key错误！'
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '历史错误响应：Secret Access错误！'
                    type: object
                    example:
                      message: 'Secret Access错误！'
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 'Secret Access错误！'
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '01 接入鉴权'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_key:
                  type: string
                  description: '接入方 Access Key，必填，最长 64 字符。'
                  example: YOUR_ACCESS_KEY
                access_secret:
                  type: string
                  description: '接入方 Secret Access，必填，最长 64 字符。'
                  example: YOUR_ACCESS_SECRET
              required:
                - access_key
                - access_secret
      security: []
  /openapi/user/info:
    post:
      summary: 查询接入方用户
      operationId: post_openapi_user_info
      description: 'account、phone 至少提供一个，同时提供必须指向同一用户。查询限定当前接入方绑定或历史 appid 用户；手机号归一化 +86/0086/86 前缀，歧义用户拒绝返回。响应 user_account 是平台主账号，可能不同于入参 account。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 查询成功
                      data:
                        user_id: 123
                        user_account: platform_demo_001
                        user_nickname: 示例用户
                        user_avatar: ''
                        user_phone: '13800000000'
                        user_created_at: '2026-10-20 10:00:00'
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 查询成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          user_id:
                            type: integer
                            example: 123
                            description: '平台用户数字 ID，不是接入方 account。'
                          user_account:
                            type: string
                            example: platform_demo_001
                            description: 平台主账号，可能与接入方外部账号不同。
                          user_nickname:
                            type: string
                            example: 示例用户
                            description: 用户昵称。
                          user_avatar:
                            type: string
                            example: ''
                            description: 头像地址，可为空。
                          user_phone:
                            type: string
                            example: '13800000000'
                            description: 手机号；为空表示未设置，不保证每个关联响应都做相同转换。
                          user_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 用户创建日期时间。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 查询条件缺失
                    type: object
                    example:
                      errorCode: 1
                      message: 请提供账号或手机号！
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 请提供账号或手机号！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 未匹配当前接入方用户
                    type: object
                    example:
                      errorCode: 1
                      message: 用户不存在、不属于当前接入方或账号与手机号不匹配！
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 用户不存在、不属于当前接入方或账号与手机号不匹配！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 历史用户歧义
                    type: object
                    example:
                      errorCode: 1
                      message: 匹配到多个历史账号，请提供更准确的账号或联系平台处理！
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 匹配到多个历史账号，请提供更准确的账号或联系平台处理！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      errorCode: 1
                      message: token验证失败，请重新获取
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方账号，最长 64 字符；与 phone 至少一个。'
                  example: partner_demo_001
                phone:
                  type: string
                  description: '手机号，最长 32 字符；与 account 至少一个，同时填写必须匹配。'
                  example: null
  /openapi/user/register:
    put:
      summary: 注册用户
      operationId: put_openapi_user_register
      description: '新接入方 account 必填，8～60 位英文、数字、下划线或短横线；既有 OpenID 接入方沿用其协议。重复注册同一接入方账号返回成功。手机号唯一命中时复用平台用户并创建接入方绑定；多个历史重复用户拒绝自动选择。openid 被其他账号绑定会失败。此接口会创建用户、绑定和默认配置，无用户详情返回；完成后可调用 user/info 查询。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：手机号格式不正确
                    type: object
                    example:
                      errorCode: 1
                      message: 手机号格式不正确
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 手机号格式不正确
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：请勿频繁操作
                    type: object
                    example:
                      errorCode: 1
                      message: 请勿频繁操作
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 请勿频繁操作
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：请输入用户唯一标识码
                    type: object
                    example:
                      message: 请输入用户唯一标识码
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 请输入用户唯一标识码
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：该openid已绑定其他账号，请使用原账号注册！
                    type: object
                    example:
                      message: 该openid已绑定其他账号，请使用原账号注册！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 该openid已绑定其他账号，请使用原账号注册！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：手机号存在多个历史账号，请联系平台处理！
                    type: object
                    example:
                      message: 手机号存在多个历史账号，请联系平台处理！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 手机号存在多个历史账号，请联系平台处理！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '新接入方必填；8～60 位，正则 ^[a-zA-Z0-9_-]+$。历史 OpenID 接入方可不传。'
                  example: partner_demo_001
                openid:
                  type: string
                  description: '用户在接入方应用内的 OpenID；既有 OpenID 接入协议必填。'
                  example: null
                unionid:
                  type: string
                  description: '微信 UnionID；可选，首次新建平台用户时保存。'
                  example: null
                name:
                  type: string
                  description: 用户昵称；不传时自动生成。
                  example: 示例用户
                phone:
                  type: string
                  description: '可选手机号，非空时校验中国大陆手机号并归一化 +86/0086/86 前缀。'
                  example: null
  /openapi/user/cancel:
    post:
      summary: 注销接入方用户绑定
      operationId: post_openapi_user_cancel
      description: '新绑定用户仅删除当前接入方的 openapi_user_binding，不删除平台用户、设备、订单或其他接入方权益。未建立新绑定的历史用户：按当前接入方 appid 查 account/OpenID，并调用账号注销流程，可能删除平台账号关联数据。重复注销已不存在的绑定不保证成功。请确认接入类型后使用。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：请输入账号！
                    type: object
                    example:
                      errorCode: 1
                      message: 请输入账号！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 请输入账号！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：当前接入方未配置用户应用！
                    type: object
                    example:
                      errorCode: 1
                      message: 当前接入方未配置用户应用！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 当前接入方未配置用户应用！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：账号不存在或不属于当前接入方！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：账号注销失败，请稍后重试！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号注销失败，请稍后重试！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号注销失败，请稍后重试！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
              required:
                - account
  /openapi/musicians/card:
    get:
      summary: 获取音乐卡
      operationId: get_openapi_musicians_card
      description: '获取全部上架音乐卡，不分页。data 中 id/name/price/value/instructions 是数据库字段的别名；value 为月数，price 为元。total 为返回数量。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          id: 1
                          name: 示例音乐月卡
                          price: '9.90'
                          value: 1
                          instructions: 一个月
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            id: 1
                            name: 示例音乐月卡
                            price: '9.90'
                            value: 1
                            instructions: 一个月
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: 示例音乐月卡
                            price:
                              type: string
                              example: '9.90'
                            value:
                              type: integer
                              example: 1
                            instructions:
                              type: string
                              example: 一个月
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/user/musicians/pay:
    put:
      summary: 购买音乐卡
      operationId: put_openapi_user_musicians_pay
      description: '使用当前接入方公司余额直接购买并发放权益：buy_type=1 会员、2 音色、3 音乐。id 取对应卡列表，金额按服务端商品价格扣减；未到期权益会续期，音色时长按 value_unit 天/月计算。会扣款并更新设备配置，重复调用可能重复扣款，不提供调用方幂等键。虽然路径叫音乐卡购买，实际支持三类卡。buy_type 在自定义校验场景中未配置规则，但业务分支依赖该值，调用方应明确传入。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：公司余额不足！
                    type: object
                    example:
                      message: 公司余额不足！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 公司余额不足！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：账号不存在！
                    type: object
                    example:
                      message: 账号不存在！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 账号不存在！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：会员卡不存在！
                    type: object
                    example:
                      message: 会员卡不存在！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 会员卡不存在！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                id:
                  type: integer
                  description: '对应卡列表的 mc_id/tc_id，整数 ≥1。'
                  example: 1
                buy_type:
                  type: integer
                  description: '权益类型：1 会员卡、2 音色卡、3 音乐卡。'
                  example: 1
                  enum:
                    - 1
                    - 2
                    - 3
              required:
                - account
                - id
                - buy_type
  /openapi/user/equity/orders:
    post:
      summary: 创建权益订单
      operationId: post_openapi_user_equity_orders
      description: '创建尚未支付的权益订单，返回 data 订单号；再调用 user/orders/pay 预支付。旧接口不支持 type=4 套餐，建议使用 V2 下单。旧逻辑使用入参 amount 作为订单金额，不代表已支付或发放。phone 为账号解析的兼容回退参数；未提供幂等键，重复调用会新建订单。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: DEMO_EQUITY_ORDER
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: string
                        example: DEMO_EQUITY_ORDER
                        description: '权益订单号，后续作为 user/orders/pay 的 code。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：该权益类型不支持！
                    type: object
                    example:
                      message: 该权益类型不支持！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 该权益类型不支持！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：账号不存在或手机号存在多个历史账号！
                    type: object
                    example:
                      message: 账号不存在或手机号存在多个历史账号！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 账号不存在或手机号存在多个历史账号！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        422:
          description: 'Laravel 参数校验失败（Accept: application/json，提示文本随语言变化）'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 请选择权益ID！
                  errors:
                    id:
                      - 请选择权益ID！
                properties:
                  message:
                    type: string
                    example: 请选择权益ID！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  errors:
                    type: object
                    properties:
                      id:
                        type: array
                        example:
                          - 请选择权益ID！
                        items:
                          type: string
                    description: 'Laravel 参数错误字典，键为参数名，值为错误提示数组；HTTP 422，提示文本随语言变化。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                id:
                  type: integer
                  description: '商品 ID，整数 ≥1。'
                  example: 1
                type:
                  type: integer
                  description: '权益类型：1 会员卡、2 音色卡、3 音乐卡。'
                  example: 1
                  enum:
                    - 1
                    - 2
                    - 3
                amount:
                  type: number
                  description: '金额（元），非负数。V2 下单实际价格由服务端商品决定。'
                  example: 9.9
                phone:
                  type: string
                  description: '可选，account 未解析到用户时，在当前接入方的用户范围内按手机号唯一匹配；不会查询其他公司的用户。'
                  example: null
              required:
                - account
                - id
                - type
                - amount
  /openapi/user/orders/pay:
    post:
      summary: 支付权益订单
      operationId: post_openapi_user_orders_pay
      description: '对旧权益订单创建微信 JSAPI 预支付单。OpenID/appid 优先来自当前接入方绑定，未绑定时读取历史用户应用信息。返回参数交给微信客户端拉起支付，预支付成功不代表付款或权益到账；需以后续支付通知为准。该旧接口使用入参 amount。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        appId: wxDEMO_APPID
                        timeStamp: '1792461600'
                        nonceStr: DEMO_NONCE
                        package: prepay_id=DEMO_PREPAY_ID
                        signType: RSA
                        paySign: DEMO_SIGNATURE
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          appId:
                            type: string
                            example: wxDEMO_APPID
                            description: '微信支付应用 ID。'
                          timeStamp:
                            type: string
                            example: '1792461600'
                            description: '微信支付 Unix 秒时间戳字符串。'
                          nonceStr:
                            type: string
                            example: DEMO_NONCE
                            description: 微信支付随机字符串。
                          package:
                            type: string
                            example: prepay_id=DEMO_PREPAY_ID
                            description: '微信预支付包，格式 prepay_id=...。'
                          signType:
                            type: string
                            example: RSA
                            description: '微信支付签名算法，例如 RSA。'
                          paySign:
                            type: string
                            example: DEMO_SIGNATURE
                            description: 支付签名字符串；示例不能用于付款。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：微信预支付失败
                    type: object
                    example:
                      errorCode: 1
                      message: 微信预支付失败
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 微信预支付失败
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: 历史错误响应：账号不存在！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 账号不存在！
                  code: 400
                properties:
                  message:
                    type: string
                    example: 账号不存在！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 400
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        422:
          description: 'Laravel 参数校验失败（Accept: application/json，提示文本随语言变化）'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 请输入订单！
                  errors:
                    code:
                      - 请输入订单！
                properties:
                  message:
                    type: string
                    example: 请输入订单！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  errors:
                    type: object
                    properties:
                      code:
                        type: array
                        example:
                          - 请输入订单！
                        items:
                          type: string
                    description: 'Laravel 参数错误字典，键为参数名，值为错误提示数组；HTTP 422，提示文本随语言变化。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                code:
                  type: string
                  description: '上一步返回的权益订单号，最长 20 字符。'
                  example: DEMO_EQUITY_ORDER
                amount:
                  type: number
                  description: '金额（元），非负数。V2 下单实际价格由服务端商品决定。'
                  example: 9.9
              required:
                - account
                - code
                - amount
  /openapi/musicians/expiretime:
    get:
      summary: 查询音乐卡到期时间
      operationId: get_openapi_musicians_expiretime
      description: '查询最后一条权益记录的到期时间；type 编号与购买类型不同：1 会员、2 音乐、3 音色，默认 1。未办理返回 HTTP 201/code=201，业务上仍属失败；此接口不是设备接口协议。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: query
          name: type
          description: '1 会员、2 音乐、3 音色；默认 1。'
          example: 1
          required: false
          schema:
            type: integer
            description: '1 会员、2 音乐、3 音色；默认 1。'
            example: 1
            enum:
              - 1
              - 2
              - 3
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      code: 200
                      errorCode: 0
                      message: ''
                      data:
                        expire_time: '2026-11-20 10:00:00'
                    properties:
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: ''
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          expire_time:
                            type: string
                            example: '2026-11-20 10:00:00'
                            description: '到期值；权益到期接口为日期时间，克隆列表为 Unix 秒，请按各接口示例解析。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        201:
          description: 历史错误响应：未办理会员卡！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 未办理会员卡！
                  code: 201
                properties:
                  message:
                    type: string
                    example: 未办理会员卡！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 201
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        400:
          description: 历史错误响应：账号不存在！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 账号不存在！
                  code: 400
                properties:
                  message:
                    type: string
                    example: 账号不存在！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 400
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        422:
          description: 'Laravel 参数校验失败（Accept: application/json，提示文本随语言变化）'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: validation.required
                  errors:
                    account:
                      - validation.required
                properties:
                  message:
                    type: string
                    example: validation.required
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  errors:
                    type: object
                    properties:
                      account:
                        type: array
                        example:
                          - validation.required
                        items:
                          type: string
                    description: 'Laravel 参数错误字典，键为参数名，值为错误提示数组；HTTP 422，提示文本随语言变化。'
      tags:
        - '02 用户与权益'
  /openapi/user/orders/v2/pay:
    post:
      summary: '支付权益订单 V2'
      operationId: post_openapi_user_orders_v2_pay
      description: '创建权益订单并获取微信 JSAPI 预支付参数。type=1 会员、2 音色、3 音乐、4 套餐；amount 仍必填但实际金额从商品价格读取。openid 与 appid 必须同源，显式 appid 必须属于当前接入方；未传时优先绑定中的 appid。套餐检查注册窗口及限购。重复调用会生成新订单；返回成功仅为预支付成功，支付回调后才发放权益。权限失败按历史协议返回 HTTP 403/code=403。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        appId: wxDEMO_APPID
                        timeStamp: '1792461600'
                        nonceStr: DEMO_NONCE
                        package: prepay_id=DEMO_PREPAY_ID
                        signType: RSA
                        paySign: DEMO_SIGNATURE
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          appId:
                            type: string
                            example: wxDEMO_APPID
                            description: '微信支付应用 ID。'
                          timeStamp:
                            type: string
                            example: '1792461600'
                            description: '微信支付 Unix 秒时间戳字符串。'
                          nonceStr:
                            type: string
                            example: DEMO_NONCE
                            description: 微信支付随机字符串。
                          package:
                            type: string
                            example: prepay_id=DEMO_PREPAY_ID
                            description: '微信预支付包，格式 prepay_id=...。'
                          signType:
                            type: string
                            example: RSA
                            description: '微信支付签名算法，例如 RSA。'
                          paySign:
                            type: string
                            example: DEMO_SIGNATURE
                            description: 支付签名字符串；示例不能用于付款。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：请选择权益ID！
                    type: object
                    example:
                      message: 请选择权益ID！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 请选择权益ID！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：权益不存在！
                    type: object
                    example:
                      message: 权益不存在！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 权益不存在！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：该权益已下架
                    type: object
                    example:
                      message: 该权益已下架
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 该权益已下架
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        403:
          description: '历史错误响应：appid 与当前接入方配置不匹配！'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'appid 与当前接入方配置不匹配！'
                  code: 403
                properties:
                  message:
                    type: string
                    example: 'appid 与当前接入方配置不匹配！'
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 403
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                id:
                  type: integer
                  description: '对应商品 ID，整数 ≥1。'
                  example: 1
                type:
                  type: integer
                  description: '1 会员、2 音色、3 音乐、4 套餐。'
                  example: 1
                  enum:
                    - 1
                    - 2
                    - 3
                    - 4
                amount:
                  type: number
                  description: '金额（元），非负数。V2 下单实际价格由服务端商品决定。'
                  example: 9.9
                openid:
                  type: string
                  description: '付款用户在该微信 appid 下的 OpenID，最长 64 字符。'
                  example: DEMO_OPENID
                appid:
                  type: string
                  description: '微信应用 ID，最长 64 字符；必须配置在当前接入方下并已绑定支付商户。'
                  example: null
              required:
                - account
                - id
                - type
                - amount
                - openid
  /openapi/user/mac/unbind:
    post:
      summary: 解除用户与设备绑定
      operationId: post_openapi_user_mac_unbind
      description: '要求 account 与 mac 存在绑定；解除该用户与设备绑定，将设备状态改为未核销并删除设备缓存。未查到设备为 HTTP 201/code=201；未查到绑定为 HTTP 202/code=202。重复调用不是幂等成功。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        201:
          description: 历史错误响应：未查到设备数据！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 未查到设备数据！
                  code: 201
                properties:
                  message:
                    type: string
                    example: 未查到设备数据！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 201
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        202:
          description: 历史错误响应：未查到绑定数据！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 未查到绑定数据！
                  code: 202
                properties:
                  message:
                    type: string
                    example: 未查到绑定数据！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 202
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        400:
          description: 历史错误响应：账号不存在！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 账号不存在！
                  code: 400
                properties:
                  message:
                    type: string
                    example: 账号不存在！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 400
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                mac:
                  type: string
                  description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
                  example: DEMO000001-DEMO-B001-WATERCUP
              required:
                - account
                - mac
  /openapi/user/mac/musicexpire:
    post:
      summary: 查询设备音乐到期时间
      operationId: post_openapi_user_mac_musicexpire
      description: '要求用户与设备已绑定。返回设备创建时间加一年计算的音乐授权日期，不是用户音乐卡到期日期。设备或绑定不存在按历史协议返回 HTTP 201/202。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        expire_date: '2027-10-20 10:00:00'
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          expire_date:
                            type: string
                            example: '2027-10-20 10:00:00'
                            description: 设备创建时间加一年计算的音乐授权到期日期时间。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        201:
          description: 历史错误响应：未查到设备数据！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 未查到设备数据！
                  code: 201
                properties:
                  message:
                    type: string
                    example: 未查到设备数据！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 201
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
        202:
          description: 历史错误响应：未查到绑定数据！
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 未查到绑定数据！
                  code: 202
                properties:
                  message:
                    type: string
                    example: 未查到绑定数据！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 202
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                mac:
                  type: string
                  description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
                  example: DEMO000001-DEMO-B001-WATERCUP
              required:
                - account
                - mac
  /openapi/user/works/list:
    post:
      summary: 获取公开智能体列表
      operationId: post_openapi_user_works_list
      description: '只返回公开且审核通过的智能体，按 works_sort、works_id 降序。使用 page/pageSize 分页，data 直接是数组，total 为总条数。关联 user/model/timbre/category 可为空；其余模型属性透传，客户端应兼容新增字段。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          works_id: 7
                          user_id: 123
                          model_id: 3
                          timbre_id: 100
                          works_name: 示例助手
                          works_avatar: ''
                          works_system: 你是一个耐心的助手。
                          works_authority: 1
                          works_status: 2
                          works_cause: ''
                          works_star: 10
                          works_created_at: '2026-10-20 10:00:00'
                          works_updated_at: '2026-10-20 10:00:00'
                          works_intro: 帮助回答日常问题
                          works_default: 2
                          wc_id: 1
                          works_sort: 1
                          works_extension: ''
                          language: zh-CN
                          user:
                            user_id: 123
                            user_account: platform_demo_001
                            user_phone: ''
                            user_nickname: 示例用户
                            user_avatar: ''
                          model:
                            model_id: 3
                            model_code: demo-model
                            model_name: 示例模型
                            model_free: 1
                          timbre:
                            timbre_id: 100
                            timbre_code: demo_voice
                            timbre_name: 示例音色
                            timbre_gender: 1
                            timbre_age_group: 3
                            timbre_tag: 自然
                            timbre_free: 1
                            timbre_platform: volcengine
                            timbre_avatar: ''
                            timbre_user_id: 0
                            timbre_expire_at: 0
                          category:
                            wc_id: 1
                            wc_title: 日常助手
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            works_id: 7
                            user_id: 123
                            model_id: 3
                            timbre_id: 100
                            works_name: 示例助手
                            works_avatar: ''
                            works_system: 你是一个耐心的助手。
                            works_authority: 1
                            works_status: 2
                            works_cause: ''
                            works_star: 10
                            works_created_at: '2026-10-20 10:00:00'
                            works_updated_at: '2026-10-20 10:00:00'
                            works_intro: 帮助回答日常问题
                            works_default: 2
                            wc_id: 1
                            works_sort: 1
                            works_extension: ''
                            language: zh-CN
                            user:
                              user_id: 123
                              user_account: platform_demo_001
                              user_phone: ''
                              user_nickname: 示例用户
                              user_avatar: ''
                            model:
                              model_id: 3
                              model_code: demo-model
                              model_name: 示例模型
                              model_free: 1
                            timbre:
                              timbre_id: 100
                              timbre_code: demo_voice
                              timbre_name: 示例音色
                              timbre_gender: 1
                              timbre_age_group: 3
                              timbre_tag: 自然
                              timbre_free: 1
                              timbre_platform: volcengine
                              timbre_avatar: ''
                              timbre_user_id: 0
                              timbre_expire_at: 0
                            category:
                              wc_id: 1
                              wc_title: 日常助手
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            works_id:
                              type: integer
                              example: 7
                            user_id:
                              type: integer
                              example: 123
                            model_id:
                              type: integer
                              example: 3
                            timbre_id:
                              type: integer
                              example: 100
                            works_name:
                              type: string
                              example: 示例助手
                            works_avatar:
                              type: string
                              example: ''
                            works_system:
                              type: string
                              example: 你是一个耐心的助手。
                            works_authority:
                              type: integer
                              example: 1
                            works_status:
                              type: integer
                              example: 2
                            works_cause:
                              type: string
                              example: ''
                            works_star:
                              type: integer
                              example: 10
                            works_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            works_updated_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            works_intro:
                              type: string
                              example: 帮助回答日常问题
                            works_default:
                              type: integer
                              example: 2
                            wc_id:
                              type: integer
                              example: 1
                            works_sort:
                              type: integer
                              example: 1
                            works_extension:
                              type: string
                              example: ''
                            language:
                              type: string
                              example: zh-CN
                            user:
                              type: object
                              properties:
                                user_id:
                                  type: integer
                                  example: 123
                                user_account:
                                  type: string
                                  example: platform_demo_001
                                user_phone:
                                  type: string
                                  example: ''
                                user_nickname:
                                  type: string
                                  example: 示例用户
                                user_avatar:
                                  type: string
                                  example: ''
                            model:
                              type: object
                              properties:
                                model_id:
                                  type: integer
                                  example: 3
                                model_code:
                                  type: string
                                  example: demo-model
                                model_name:
                                  type: string
                                  example: 示例模型
                                model_free:
                                  type: integer
                                  example: 1
                            timbre:
                              type: object
                              properties:
                                timbre_id:
                                  type: integer
                                  example: 100
                                timbre_code:
                                  type: string
                                  example: demo_voice
                                timbre_name:
                                  type: string
                                  example: 示例音色
                                timbre_gender:
                                  type: integer
                                  example: 1
                                timbre_age_group:
                                  type: integer
                                  example: 3
                                timbre_tag:
                                  type: string
                                  example: 自然
                                timbre_free:
                                  type: integer
                                  example: 1
                                timbre_platform:
                                  type: string
                                  example: volcengine
                                timbre_avatar:
                                  type: string
                                  example: ''
                                timbre_user_id:
                                  type: integer
                                  example: 0
                                timbre_expire_at:
                                  type: integer
                                  example: 0
                            category:
                              type: object
                              properties:
                                wc_id:
                                  type: integer
                                  example: 1
                                wc_title:
                                  type: string
                                  example: 日常助手
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: '页码，从 1 开始，默认 1。'
                  example: 1
                pageSize:
                  type: integer
                  description: '每页数量，默认 10。'
                  example: 10
                works_name:
                  type: string
                  description: 名称模糊搜索。
                  example: null
                model_id:
                  type: integer
                  description: '模型 ID。'
                  example: null
                works_default:
                  type: integer
                  description: '1 默认、2 非默认；不传则不筛选。'
                  example: null
                  enum:
                    - 1
                    - 2
                wc_id:
                  type: integer
                  description: '分类 ID，兼容逗号分隔分类字段匹配。'
                  example: null
  /openapi/timbre/list:
    get:
      summary: 获取音色列表
      operationId: get_openapi_timbre_list
      description: '返回公共启用音色（timbre_user_id=0，状态固定为启用；传 timbre_status 不生效）。用户设备批次可限制平台范围。page/pageSize 至少按 1 处理，data 数组，total 总数。账户不存在返回 HTTP 405/code=405。类型常见值：1 拟人、2 情感、9 普通。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: query
          name: page
          description: '页码，从 1 开始，默认 1。'
          example: 1
          required: false
          schema:
            type: integer
            description: '页码，从 1 开始，默认 1。'
            example: 1
        -
          in: query
          name: pageSize
          description: '每页数量，默认 20。'
          example: 20
          required: false
          schema:
            type: integer
            description: '每页数量，默认 20。'
            example: 20
        -
          in: query
          name: timbre_name
          description: 音色名模糊搜索。
          example: null
          required: false
          schema:
            type: string
            description: 音色名模糊搜索。
            example: null
        -
          in: query
          name: timbre_platform
          description: '音色提供平台，例如 volcengine；以返回值为准。'
          example: null
          required: false
          schema:
            type: string
            description: '音色提供平台，例如 volcengine；以返回值为准。'
            example: null
        -
          in: query
          name: timbre_free
          description: '1 免费、2 收费。'
          example: null
          required: false
          schema:
            type: integer
            description: '1 免费、2 收费。'
            example: null
            enum:
              - 1
              - 2
        -
          in: query
          name: timbre_type
          description: '1 拟人、2 情感、9 普通。'
          example: null
          required: false
          schema:
            type: integer
            description: '1 拟人、2 情感、9 普通。'
            example: null
            enum:
              - 1
              - 2
              - 9
        -
          in: query
          name: timbre_status
          description: '兼容旧参数，当前始终按启用状态 1 查询。'
          example: null
          required: false
          schema:
            type: integer
            description: '兼容旧参数，当前始终按启用状态 1 查询。'
            example: null
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          timbre_id: 100
                          timbre_code: demo_voice
                          timbre_name: 示例音色
                          timbre_gender: 1
                          timbre_age_group: 3
                          timbre_status: 1
                          timbre_tag: 自然
                          timbre_created_at: '2026-10-20 10:00:00'
                          timbre_free: 1
                          timbre_platform: volcengine
                          timbre_avatar: ''
                          timbre_audio: ''
                          timbre_sort: 1
                          timbre_recommended: 2
                          timbre_type: 1
                          timbre_user_id: 0
                          timbre_expire_at: 0
                          timbre_user_upload_audio: ''
                          timbre_error_msg: ''
                          timbre_state: ''
                          timbre_remaining_nums: 0
                          timbre_order_id: 0
                          language: zh-CN
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            timbre_id: 100
                            timbre_code: demo_voice
                            timbre_name: 示例音色
                            timbre_gender: 1
                            timbre_age_group: 3
                            timbre_status: 1
                            timbre_tag: 自然
                            timbre_created_at: '2026-10-20 10:00:00'
                            timbre_free: 1
                            timbre_platform: volcengine
                            timbre_avatar: ''
                            timbre_audio: ''
                            timbre_sort: 1
                            timbre_recommended: 2
                            timbre_type: 1
                            timbre_user_id: 0
                            timbre_expire_at: 0
                            timbre_user_upload_audio: ''
                            timbre_error_msg: ''
                            timbre_state: ''
                            timbre_remaining_nums: 0
                            timbre_order_id: 0
                            language: zh-CN
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            timbre_id:
                              type: integer
                              example: 100
                            timbre_code:
                              type: string
                              example: demo_voice
                            timbre_name:
                              type: string
                              example: 示例音色
                            timbre_gender:
                              type: integer
                              example: 1
                            timbre_age_group:
                              type: integer
                              example: 3
                            timbre_status:
                              type: integer
                              example: 1
                            timbre_tag:
                              type: string
                              example: 自然
                            timbre_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            timbre_free:
                              type: integer
                              example: 1
                            timbre_platform:
                              type: string
                              example: volcengine
                            timbre_avatar:
                              type: string
                              example: ''
                            timbre_audio:
                              type: string
                              example: ''
                            timbre_sort:
                              type: integer
                              example: 1
                            timbre_recommended:
                              type: integer
                              example: 2
                            timbre_type:
                              type: integer
                              example: 1
                            timbre_user_id:
                              type: integer
                              example: 0
                            timbre_expire_at:
                              type: integer
                              example: 0
                            timbre_user_upload_audio:
                              type: string
                              example: ''
                            timbre_error_msg:
                              type: string
                              example: ''
                            timbre_state:
                              type: string
                              example: ''
                            timbre_remaining_nums:
                              type: integer
                              example: 0
                            timbre_order_id:
                              type: integer
                              example: 0
                            language:
                              type: string
                              example: zh-CN
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        405:
          description: 历史错误响应：用户账号不存在
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 用户账号不存在
                  code: 405
                properties:
                  message:
                    type: string
                    example: 用户账号不存在
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 405
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
  /openapi/timbre/cardList:
    get:
      summary: 获取音色卡列表
      operationId: get_openapi_timbre_cardList
      description: '返回上架音色卡，不分页，按 tc_id 降序。addr_type 默认 1；传 0 时当前逻辑不按地区筛选。value_unit=1 月、2 天；tc_permissions 为逗号分隔权限，1 拟人、2 情感。'
      parameters:
        -
          in: query
          name: tc_name
          description: 音色卡名称模糊搜索。
          example: null
          required: false
          schema:
            type: string
            description: 音色卡名称模糊搜索。
            example: null
        -
          in: query
          name: addr_type
          description: '1 国内、2 国外；默认 1，0 不筛选。'
          example: 1
          required: false
          schema:
            type: integer
            description: '1 国内、2 国外；默认 1，0 不筛选。'
            example: 1
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          tc_id: 1
                          tc_name: 示例月卡
                          tc_price: '9.90'
                          tc_value: 1
                          tc_status: 1
                          tc_instructions: 有效期一个月
                          tc_created_at: '2026-10-20 10:00:00'
                          tc_unique_value: demo_month
                          language: zh-CN
                          addr_type: 1
                          value_unit: 1
                          tc_permissions: '1,2'
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            tc_id: 1
                            tc_name: 示例月卡
                            tc_price: '9.90'
                            tc_value: 1
                            tc_status: 1
                            tc_instructions: 有效期一个月
                            tc_created_at: '2026-10-20 10:00:00'
                            tc_unique_value: demo_month
                            language: zh-CN
                            addr_type: 1
                            value_unit: 1
                            tc_permissions: '1,2'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            tc_id:
                              type: integer
                              example: 1
                            tc_name:
                              type: string
                              example: 示例月卡
                            tc_price:
                              type: string
                              example: '9.90'
                            tc_value:
                              type: integer
                              example: 1
                            tc_status:
                              type: integer
                              example: 1
                            tc_instructions:
                              type: string
                              example: 有效期一个月
                            tc_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            tc_unique_value:
                              type: string
                              example: demo_month
                            language:
                              type: string
                              example: zh-CN
                            addr_type:
                              type: integer
                              example: 1
                            value_unit:
                              type: integer
                              example: 1
                            tc_permissions:
                              type: string
                              example: '1,2'
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/music/cardList:
    get:
      summary: 获取音乐卡列表
      operationId: get_openapi_music_cardList
      description: '返回上架音乐卡，不分页，按 mc_id 降序。mc_value 为月数；价格为元。addr_type 默认 1，传 0 时不筛选地区。'
      parameters:
        -
          in: query
          name: mc_name
          description: 音乐卡名称模糊搜索。
          example: null
          required: false
          schema:
            type: string
            description: 音乐卡名称模糊搜索。
            example: null
        -
          in: query
          name: addr_type
          description: '1 国内、2 国外；默认 1，0 不筛选。'
          example: 1
          required: false
          schema:
            type: integer
            description: '1 国内、2 国外；默认 1，0 不筛选。'
            example: 1
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          mc_id: 1
                          mc_name: 示例月卡
                          mc_price: '9.90'
                          mc_value: 1
                          mc_status: 1
                          mc_instructions: 有效期一个月
                          mc_created_at: '2026-10-20 10:00:00'
                          mc_unique_value: demo_month
                          language: zh-CN
                          addr_type: 1
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            mc_id: 1
                            mc_name: 示例月卡
                            mc_price: '9.90'
                            mc_value: 1
                            mc_status: 1
                            mc_instructions: 有效期一个月
                            mc_created_at: '2026-10-20 10:00:00'
                            mc_unique_value: demo_month
                            language: zh-CN
                            addr_type: 1
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            mc_id:
                              type: integer
                              example: 1
                            mc_name:
                              type: string
                              example: 示例月卡
                            mc_price:
                              type: string
                              example: '9.90'
                            mc_value:
                              type: integer
                              example: 1
                            mc_status:
                              type: integer
                              example: 1
                            mc_instructions:
                              type: string
                              example: 有效期一个月
                            mc_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            mc_unique_value:
                              type: string
                              example: demo_month
                            language:
                              type: string
                              example: zh-CN
                            addr_type:
                              type: integer
                              example: 1
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/membership/cardList:
    get:
      summary: 获取会员卡列表
      operationId: get_openapi_membership_cardList
      description: '返回上架会员卡，不分页，按 mc_id 降序。mc_value 为月数；价格为元。addr_type 默认 1，传 0 时不筛选地区。'
      parameters:
        -
          in: query
          name: mc_name
          description: 会员卡名称模糊搜索。
          example: null
          required: false
          schema:
            type: string
            description: 会员卡名称模糊搜索。
            example: null
        -
          in: query
          name: addr_type
          description: '1 国内、2 国外；默认 1，0 不筛选。'
          example: 1
          required: false
          schema:
            type: integer
            description: '1 国内、2 国外；默认 1，0 不筛选。'
            example: 1
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          mc_id: 1
                          mc_name: 示例月卡
                          mc_price: '9.90'
                          mc_value: 1
                          mc_status: 1
                          mc_instructions: 有效期一个月
                          mc_created_at: '2026-10-20 10:00:00'
                          mc_unique_value: demo_month
                          language: zh-CN
                          addr_type: 1
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            mc_id: 1
                            mc_name: 示例月卡
                            mc_price: '9.90'
                            mc_value: 1
                            mc_status: 1
                            mc_instructions: 有效期一个月
                            mc_created_at: '2026-10-20 10:00:00'
                            mc_unique_value: demo_month
                            language: zh-CN
                            addr_type: 1
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            mc_id:
                              type: integer
                              example: 1
                            mc_name:
                              type: string
                              example: 示例月卡
                            mc_price:
                              type: string
                              example: '9.90'
                            mc_value:
                              type: integer
                              example: 1
                            mc_status:
                              type: integer
                              example: 1
                            mc_instructions:
                              type: string
                              example: 有效期一个月
                            mc_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            mc_unique_value:
                              type: string
                              example: demo_month
                            language:
                              type: string
                              example: zh-CN
                            addr_type:
                              type: integer
                              example: 1
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/work/bind-to-device:
    patch:
      summary: 绑定智能体到设备
      operationId: patch_openapi_work_bind_to_device
      description: '将智能体配置到用户当前绑定的所有设备，不接受单个 mac_id。timbre_id 不传时使用智能体默认音色；检查批次平台、模型会员、普通/情感音色权限。会更新绑定及缓存、增加智能体热度；重复调用可能重复增加热度。服务端成功不等于设备已应用。建议先确认 works_id 有效，当前方法未单独处理智能体不存在的空值。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：音色不存在！
                    type: object
                    example:
                      errorCode: 1
                      message: 音色不存在！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 音色不存在！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：没有该音色权限！
                    type: object
                    example:
                      errorCode: 1
                      message: 没有该音色权限！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 没有该音色权限！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：需开通高级AI模型VIP！
                    type: object
                    example:
                      errorCode: 1
                      message: 需开通高级AI模型VIP！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 需开通高级AI模型VIP！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：需开通情感音色VIP！
                    type: object
                    example:
                      errorCode: 1
                      message: 需开通情感音色VIP！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 需开通情感音色VIP！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        422:
          description: 'Laravel 参数校验失败（Accept: application/json，提示文本随语言变化）'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 请选择作品ID！
                  errors:
                    works_id:
                      - 请选择作品ID！
                properties:
                  message:
                    type: string
                    example: 请选择作品ID！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  errors:
                    type: object
                    properties:
                      works_id:
                        type: array
                        example:
                          - 请选择作品ID！
                        items:
                          type: string
                    description: 'Laravel 参数错误字典，键为参数名，值为错误提示数组；HTTP 422，提示文本随语言变化。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                works_id:
                  type: integer
                  description: '目标智能体 ID，整数 ≥1。'
                  example: 7
                timbre_id:
                  type: integer
                  description: '覆盖智能体默认音色的 ID；不传时沿用默认。'
                  example: null
                imei:
                  type: string
                  description: '可选设备 IMEI；未传时缓存中写空字符串。'
                  example: null
                devideid:
                  type: string
                  description: '兼容字段，拼写为 devideid；未传时缓存中写空字符串。'
                  example: null
              required:
                - account
                - works_id
  /openapi/user/device/info:
    get:
      summary: 获取用户设备信息
      operationId: get_openapi_user_device_info
      description: '查询当前接入方用户的第一台绑定设备，产品名按 Accept-Language 本地化。账号不存在或不属于当前接入方时失败；用户未绑定设备时仍成功，基础产品字段为空。附加 user_city，有设备时附加 mac_code/user_imei。多个设备请改用 user/devices/info。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        serial_code: DEMO000001
                        batch_code: B001
                        product_code: WATERCUP
                        product_name: 示例水杯
                        user_city: ''
                        mac_code: DEMO000001-DEMO-B001-WATERCUP
                        user_imei: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          serial_code:
                            type: string
                            example: DEMO000001
                            description: 设备编码第一段序列号。
                          batch_code:
                            type: string
                            example: B001
                            description: 批次编码。
                          product_code:
                            type: string
                            example: WATERCUP
                            description: 产品编码（单设备接口拼写）。
                          product_name:
                            type: string
                            example: 示例水杯
                            description: 按请求语言本地化的产品名称。
                          user_city:
                            type: string
                            example: ''
                            description: 用户城市，可为空。
                          mac_code:
                            type: string
                            example: DEMO000001-DEMO-B001-WATERCUP
                            description: 完整设备编码。
                          user_imei:
                            type: string
                            example: ''
                            description: '从设备配置读取的 IMEI，可为空。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        serial_code: ''
                        batch_code: ''
                        product_code: ''
                        product_name: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          serial_code:
                            type: string
                            example: ''
                            description: 设备编码第一段序列号。
                          batch_code:
                            type: string
                            example: ''
                            description: 批次编码。
                          product_code:
                            type: string
                            example: ''
                            description: 产品编码（单设备接口拼写）。
                          product_name:
                            type: string
                            example: ''
                            description: 按请求语言本地化的产品名称。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        422:
          description: 'Laravel 参数校验失败（Accept: application/json，提示文本随语言变化）'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 请输入账号！
                  errors:
                    account:
                      - 请输入账号！
                properties:
                  message:
                    type: string
                    example: 请输入账号！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  errors:
                    type: object
                    properties:
                      account:
                        type: array
                        example:
                          - 请输入账号！
                        items:
                          type: string
                    description: 'Laravel 参数错误字典，键为参数名，值为错误提示数组；HTTP 422，提示文本随语言变化。'
      tags:
        - '02 用户与权益'
  /openapi/user/update/pwd:
    post:
      summary: 修改用户密码
      operationId: post_openapi_user_update_pwd
      description: '使用中国大陆手机号及已有短信验证码重置密码。手机号必须在当前接入方的用户范围内唯一解析到平台用户；无权访问的用户按手机号未注册返回。成功后立即删除验证码并更新密码。此开放平台路由组没有发送短信验证码接口，验证码需由既有业务流程获取。本接口不做 +86 前缀兼容。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：手机号未注册
                    type: object
                    example:
                      errorCode: 1
                      message: 手机号未注册
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 手机号未注册
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：验证码已过期或不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 验证码已过期或不存在
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 验证码已过期或不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：验证码错误
                    type: object
                    example:
                      errorCode: 1
                      message: 验证码错误
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 验证码错误
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  description: '11 位中国大陆手机号，正则 ^1\d{10}$。'
                  example: '13800000000'
                verification_code:
                  type: string
                  description: 已有短信验证码，一次性使用。
                  example: '000000'
                new_password:
                  type: string
                  description: '新密码，字符串至少 6 字符。'
                  example: DemoPassword123
              required:
                - phone
                - verification_code
                - new_password
  /openapi/user/up/studentId:
    post:
      summary: 更新用户学号
      operationId: post_openapi_user_up_studentId
      description: '按 account 更新或创建用户资料中的学号，不改变登录账号。account、student_id 必须是字符串且各不超过 64 字符。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：账号不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                student_id:
                  type: string
                  description: '学号，最长 64 字符。'
                  example: DEMO2026001
              required:
                - account
                - student_id
  /openapi/corporation/balance/log:
    get:
      summary: 查询公司余额及扣减记录
      operationId: get_openapi_corporation_balance_log
      description: 'type=0 默认返回当前公司余额；非 0 查询余额变动日志，page/pageSize 分页。create_time 按 cbl_created_at 的下界直接比较，建议传日期时间字符串；未传时历史代码使用 Unix 秒值，请显式传入避免时间类型歧义。日志查询当前实现按分片读取，未额外添加 corporation_id 条件；返回范围不能视为已验证的租户隔离，仅应由有权限的接入方使用。'
      parameters:
        -
          in: query
          name: type
          description: '0 余额；非 0 余额日志，默认 0。'
          example: 0
          required: false
          schema:
            type: integer
            description: '0 余额；非 0 余额日志，默认 0。'
            example: 0
        -
          in: query
          name: page
          description: '页码，从 1 开始，默认 1。'
          example: 1
          required: false
          schema:
            type: integer
            description: '页码，从 1 开始，默认 1。'
            example: 1
        -
          in: query
          name: pageSize
          description: '每页数量，默认 20。'
          example: 20
          required: false
          schema:
            type: integer
            description: '每页数量，默认 20。'
            example: 20
        -
          in: query
          name: create_time
          description: '日志开始时间，建议 Y-m-d H:i:s；仅日志模式使用。'
          example: '2026-10-01 00:00:00'
          required: false
          schema:
            type: string
            description: '日志开始时间，建议 Y-m-d H:i:s；仅日志模式使用。'
            example: '2026-10-01 00:00:00'
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        corporation_balance: '100.00'
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          corporation_balance:
                            type: string
                            example: '100.00'
                            description: 当前公司余额，单位元。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        list:
                          -
                            cbl_type: 2
                            cbl_raw_balance: '100.00'
                            cbl_now_balance: '90.10'
                            cbl_balance: '9.90'
                            cbl_remarks: 购买示例月卡
                            cbl_created_at: '2026-10-20 10:00:00'
                        count: 1
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          list:
                            type: array
                            example:
                              -
                                cbl_type: 2
                                cbl_raw_balance: '100.00'
                                cbl_now_balance: '90.10'
                                cbl_balance: '9.90'
                                cbl_remarks: 购买示例月卡
                                cbl_created_at: '2026-10-20 10:00:00'
                            description: 余额日志列表。
                            items:
                              type: object
                              properties:
                                cbl_type:
                                  type: integer
                                  example: 2
                                cbl_raw_balance:
                                  type: string
                                  example: '100.00'
                                cbl_now_balance:
                                  type: string
                                  example: '90.10'
                                cbl_balance:
                                  type: string
                                  example: '9.90'
                                cbl_remarks:
                                  type: string
                                  example: 购买示例月卡
                                cbl_created_at:
                                  type: string
                                  example: '2026-10-20 10:00:00'
                          count:
                            type: integer
                            example: 1
                            description: 匹配记录总数。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/work/add:
    post:
      summary: 新增智能体
      operationId: post_openapi_work_add
      description: '创建用户智能体。model_id=20 时 works_extension 必填；公开智能体不能使用私人克隆音色。账号封控时拒绝创建。wc_id 优先由接入方公司配置覆盖；创建成功不返回 ID，也不代表已审核通过。works_avatar 可使用 work/avatar 返回地址。该方法会透传非 null 入参给模型，仅提交文档列出的业务字段。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：账号必填
                    type: object
                    example:
                      errorCode: 1
                      message: 账号必填
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号必填
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：请选择模型ID！
                    type: object
                    example:
                      errorCode: 1
                      message: 请选择模型ID！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 请选择模型ID！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：该音色暂不支持创建公开智能体！
                    type: object
                    example:
                      errorCode: 1
                      message: 该音色暂不支持创建公开智能体！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 该音色暂不支持创建公开智能体！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                model_id:
                  type: integer
                  description: '模型 ID，整数 ≥1。'
                  example: 3
                timbre_id:
                  type: integer
                  description: '音色 ID，整数 ≥1。'
                  example: 100
                works_name:
                  type: string
                  description: '智能体名称，最长 64 字符。'
                  example: 示例助手
                works_avatar:
                  type: string
                  description: '头像地址，最长 128 字符；先上传头像获取。'
                  example: 'https://example.com/avatar.jpg'
                works_system:
                  type: string
                  description: '角色设定，最大 3000 字符。'
                  example: 你是一个耐心的助手。
                works_authority:
                  type: integer
                  description: '1 公开、2 私密；校验仅要求整数 ≥1，调用时使用这两种业务值。'
                  example: 2
                works_extension:
                  type: string
                  description: '扩展配置字符串，model_id=20 时必填。'
                  example: null
                works_intro:
                  type: string
                  description: '可选简介，由 Works 模型透传保存。'
                  example: 帮助回答日常问题
                wc_id:
                  type: integer
                  description: 可选分类；公司配置存在时被覆盖。
                  example: null
                language:
                  type: string
                  description: 可选智能体语言代码。
                  example: zh-CN
              required:
                - account
                - model_id
                - timbre_id
                - works_name
                - works_avatar
                - works_system
                - works_authority
  /openapi/work/stream:
    post:
      summary: '智能体优化 · 流式对话'
      operationId: post_openapi_work_stream
      description: '优化角色设定的流式对话，推荐 POST JSON。当前实现固定 works_id=15，不能通过入参切换。返回 SSE：普通 data 为 {time,content}，中文可能按字拆分；关闭帧 event: close 的 data 是文本 Connection closed，不能全部当 JSON 解析。断开前不表示完整回答；浏览器调试器可能流结束后统一展示。依赖模型密钥及上游服务，异常也可能中断连接。实时示例：`curl -N -X POST http://localhost:8000/openapi/work/stream -H ''Authorization: Bearer YOUR_TOKEN'' -H ''Content-Type: application/json'' -d ''{"account":"partner_demo_001","content":"帮我优化角色设定"}''`。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: 'SSE 成功分片与结束帧示例'
          content:
            text/event-stream:
              schema:
                type: string
              example: "data: {\"time\":\"2026-10-20 10:00:00\",\"content\":\"你\"}\n\nevent: close\ndata: Connection closed\n\n"
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                content:
                  type: string
                  description: 用户输入文本；当前代码没有独立必填校验，空输入可能回退默认问候。
                  example: 帮我优化角色设定
              required:
                - account
  /openapi/chat/list:
    get:
      summary: 获取用户对话记录
      operationId: get_openapi_chat_list
      description: '按当前接入方公司查询当前月份分表的对话记录，按 chat_id 降序；时间条件不会使此入口自动跨月查询。account 和 phone 都传时，phone 会覆盖 account 解析结果，不是取交集。chat_type=0 因历史 empty 判断不会增加类型过滤。分页 data 为数组，total 总数。返回用户、智能体、模型和来源说明；原始聊天模型字段透传，缺失关联可能使请求失败。'
      parameters:
        -
          in: query
          name: page
          description: '页码，从 1 开始，默认 1。'
          example: 1
          required: false
          schema:
            type: integer
            description: '页码，从 1 开始，默认 1。'
            example: 1
        -
          in: query
          name: pageSize
          description: '每页数量，默认 20。'
          example: 20
          required: false
          schema:
            type: integer
            description: '每页数量，默认 20。'
            example: 20
        -
          in: query
          name: account
          description: 可选接入方用户账号。
          example: null
          required: false
          schema:
            type: string
            description: 可选接入方用户账号。
            example: null
        -
          in: query
          name: phone
          description: '可选用户手机号；与 account 同传时覆盖其查询条件。'
          example: null
          required: false
          schema:
            type: string
            description: '可选用户手机号；与 account 同传时覆盖其查询条件。'
            example: null
        -
          in: query
          name: mac_code
          description: 完整设备编码筛选。
          example: null
          required: false
          schema:
            type: string
            description: 完整设备编码筛选。
            example: null
        -
          in: query
          name: chat_type
          description: '1 音乐、2 天气、3 闹钟、4 没听清、5 计算、6 指令词、7 内容、8 播客、13 笔画；0 当前不筛选。'
          example: null
          required: false
          schema:
            type: integer
            description: '1 音乐、2 天气、3 闹钟、4 没听清、5 计算、6 指令词、7 内容、8 播客、13 笔画；0 当前不筛选。'
            example: null
        -
          in: query
          name: chat_issue
          description: 提问内容筛选，由聊天查询模型处理。
          example: null
          required: false
          schema:
            type: string
            description: 提问内容筛选，由聊天查询模型处理。
            example: null
        -
          in: query
          name: chat_created_at_start
          description: '开始时间，支持 Y-m-d 或 Y-m-d H:i:s（北京时间），包含边界；仅日期按 00:00:00。不传则不限开始时间。'
          example: null
          required: false
          schema:
            type: string
            description: '开始时间，支持 Y-m-d 或 Y-m-d H:i:s（北京时间），包含边界；仅日期按 00:00:00。不传则不限开始时间。'
            example: null
        -
          in: query
          name: chat_created_at_end
          description: '结束时间，支持 Y-m-d 或 Y-m-d H:i:s（北京时间），包含边界；仅日期按 23:59:59。不得早于开始时间；不传则不限结束时间。仅查询当前月份分表。'
          example: null
          required: false
          schema:
            type: string
            description: '结束时间，支持 Y-m-d 或 Y-m-d H:i:s（北京时间），包含边界；仅日期按 23:59:59。不得早于开始时间；不传则不限结束时间。仅查询当前月份分表。'
            example: null
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          chat_id: 1
                          user_id: 123
                          works_id: 7
                          model_id: 3
                          corporation_id: 1
                          chat_type: 0
                          source: 1
                          chat_issue: 你好
                          chat_reply: 你好！
                          chat_created_at: '2026-10-20 10:00:00'
                          corporation_name: 示例接入方
                          user_phone: ''
                          works_name: 示例助手
                          user_account: platform_demo_001
                          model_name: 示例模型
                          chat_type_source: 大模型(设备)
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            chat_id: 1
                            user_id: 123
                            works_id: 7
                            model_id: 3
                            corporation_id: 1
                            chat_type: 0
                            source: 1
                            chat_issue: 你好
                            chat_reply: 你好！
                            chat_created_at: '2026-10-20 10:00:00'
                            corporation_name: 示例接入方
                            user_phone: ''
                            works_name: 示例助手
                            user_account: platform_demo_001
                            model_name: 示例模型
                            chat_type_source: 大模型(设备)
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            chat_id:
                              type: integer
                              example: 1
                            user_id:
                              type: integer
                              example: 123
                            works_id:
                              type: integer
                              example: 7
                            model_id:
                              type: integer
                              example: 3
                            corporation_id:
                              type: integer
                              example: 1
                            chat_type:
                              type: integer
                              example: 0
                            source:
                              type: integer
                              example: 1
                            chat_issue:
                              type: string
                              example: 你好
                            chat_reply:
                              type: string
                              example: 你好！
                            chat_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            corporation_name:
                              type: string
                              example: 示例接入方
                            user_phone:
                              type: string
                              example: ''
                            works_name:
                              type: string
                              example: 示例助手
                            user_account:
                              type: string
                              example: platform_demo_001
                            model_name:
                              type: string
                              example: 示例模型
                            chat_type_source:
                              type: string
                              example: 大模型(设备)
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
  /openapi/work/get/user/timbre:
    post:
      summary: 获取用户配置音色
      operationId: post_openapi_work_get_user_timbre
      description: '读取用户第一台绑定设备的完整配置缓存，移除 works_system 后返回；并非只返回音色字段。不同设备配置键可能不同，应兼容新增或缺失属性。用户或绑定不存在失败；缓存缺失时返回缓存工具的空值。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        works_id: 7
                        model_id: 3
                        model_code: demo-model
                        timbre_id: 100
                        timbre_code: demo_voice
                        timbre_platform: volcengine
                        timbre_free: 1
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          works_id:
                            type: integer
                            example: 7
                            description: '智能体 ID；缓存读取时可能是字符串。'
                          model_id:
                            type: integer
                            example: 3
                            description: '模型 ID。'
                          model_code:
                            type: string
                            example: demo-model
                            description: 模型运行标识。
                          timbre_id:
                            type: integer
                            example: 100
                            description: '音色 ID。'
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          timbre_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费；是否可使用仍需结合权益和批次权限。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
              required:
                - account
  /openapi/get/timbre:
    get:
      summary: '按 ID 查询音色'
      operationId: get_openapi_get_timbre
      description: '按 timbre_id 返回音色原始模型字段，不额外筛选启用状态或所有者。缺少 ID 业务失败；ID 存在但查不到记录时仍成功且 data=null。'
      parameters:
        -
          in: query
          name: timbre_id
          description: '音色 ID，注意参数名不是 id。'
          example: 100
          required: true
          schema:
            type: integer
            description: '音色 ID，注意参数名不是 id。'
            example: 100
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        timbre_id: 100
                        timbre_code: demo_voice
                        timbre_name: 示例音色
                        timbre_gender: 1
                        timbre_age_group: 3
                        timbre_status: 1
                        timbre_tag: 自然
                        timbre_created_at: '2026-10-20 10:00:00'
                        timbre_free: 1
                        timbre_platform: volcengine
                        timbre_avatar: ''
                        timbre_audio: ''
                        timbre_sort: 1
                        timbre_recommended: 2
                        timbre_type: 1
                        timbre_user_id: 0
                        timbre_expire_at: 0
                        timbre_user_upload_audio: ''
                        timbre_error_msg: ''
                        timbre_state: ''
                        timbre_remaining_nums: 0
                        timbre_order_id: 0
                        language: zh-CN
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          timbre_id:
                            type: integer
                            example: 100
                            description: '音色 ID。'
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_name:
                            type: string
                            example: 示例音色
                            description: 音色名称。
                          timbre_gender:
                            type: integer
                            example: 1
                            description: '1 男、2 女。'
                          timbre_age_group:
                            type: integer
                            example: 3
                            description: '1 童年、2 青年、3 成年、4 中年、5 老年。'
                          timbre_status:
                            type: integer
                            example: 1
                            description: '1 启用、2 禁用。'
                          timbre_tag:
                            type: string
                            example: 自然
                            description: 音色标签。
                          timbre_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 音色创建日期时间。
                          timbre_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费；是否可使用仍需结合权益和批次权限。'
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          timbre_avatar:
                            type: string
                            example: ''
                            description: 音色头像地址，可为空。
                          timbre_audio:
                            type: string
                            example: ''
                            description: 试听音频地址，可为空。
                          timbre_sort:
                            type: integer
                            example: 1
                            description: 音色排序值，越大越靠前。
                          timbre_recommended:
                            type: integer
                            example: 2
                            description: '1 推荐、2 非推荐。'
                          timbre_type:
                            type: integer
                            example: 1
                            description: '音色类型：1 拟人、2 情感、9 普通。'
                          timbre_user_id:
                            type: integer
                            example: 0
                            description: '音色所属平台用户 ID；0 表示公共音色。'
                          timbre_expire_at:
                            type: integer
                            example: 0
                            description: '克隆音色过期 Unix 时间戳（秒）；公共音色可为 0。'
                          timbre_user_upload_audio:
                            type: string
                            example: ''
                            description: 用户上传的训练音频地址。
                          timbre_error_msg:
                            type: string
                            example: ''
                            description: 训练/审核说明；非空时需检查业务状态。
                          timbre_state:
                            type: string
                            example: ''
                            description: '训练状态，例如 Training、Success、Failed、Active、Unknown，以上游结果为准。'
                          timbre_remaining_nums:
                            type: integer
                            example: 0
                            description: 剩余重新录音次数；是否扣减以具体流程为准。
                          timbre_order_id:
                            type: integer
                            example: 0
                            description: '关联克隆名额订单 ID。'
                          language:
                            type: string
                            example: zh-CN
                            description: '语言代码，例如 zh-CN。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data: null
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: string
                        example: null
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：音色id不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 音色id不存在
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 音色id不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/get/models:
    get:
      summary: '按 ID 查询模型'
      operationId: get_openapi_get_models
      description: '按 models_id 返回模型原始字段。参数名是复数 models_id；不额外过滤启用状态。缺少 ID 业务失败，查不到时成功且 data=null。'
      parameters:
        -
          in: query
          name: models_id
          description: '模型 ID，注意是 models_id。'
          example: 3
          required: true
          schema:
            type: integer
            description: '模型 ID，注意是 models_id。'
            example: 3
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        model_id: 3
                        model_code: demo-model
                        model_name: 示例模型
                        model_status: 1
                        model_created_at: '2026-10-20 10:00:00'
                        model_avatar: ''
                        model_show: 1
                        model_free: 1
                        model_sort: 1
                        language: zh-CN
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          model_id:
                            type: integer
                            example: 3
                            description: '模型 ID。'
                          model_code:
                            type: string
                            example: demo-model
                            description: 模型运行标识。
                          model_name:
                            type: string
                            example: 示例模型
                            description: 模型显示名称。
                          model_status:
                            type: integer
                            example: 1
                            description: '1 启用、2 禁用。'
                          model_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 模型创建时间。
                          model_avatar:
                            type: string
                            example: ''
                            description: 模型头像地址，可为空。
                          model_show:
                            type: integer
                            example: 1
                            description: '1 显示、2 不显示。'
                          model_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费，收费模型通常需要有效会员。'
                          model_sort:
                            type: integer
                            example: 1
                            description: 模型排序值，越大越靠前。
                          language:
                            type: string
                            example: zh-CN
                            description: '语言代码，例如 zh-CN。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data: null
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: string
                        example: null
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：模型id不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 模型id不存在
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 模型id不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '02 用户与权益'
  /openapi/user/devices/info:
    get:
      summary: 获取用户设备列表
      operationId: get_openapi_user_devices_info
      description: '返回用户全部绑定设备；无设备返回 data=[]，用户不存在失败。产品名按 Accept-Language 返回。保留历史字段拼写 proudct_code（与单设备接口 product_code 不同）。switch_prologue 取设备缓存，缺失默认 0。OTA 按设备编码的公司、批次、产品取最新配置，与设备下载接口一致。version 是设备最后上报的版本，可能为空或滞后；new_version 是可用固件版本，无配置或本地文件缺失时为空；can_upgrade 为是否可升级，未上报版本且有固件时为 true；upgrade_reason 为升级说明。远程固件不在查询时探测可达性。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        -
                          mac_id: 1
                          serial_code: DEMO000001
                          batch_code: B001
                          proudct_code: WATERCUP
                          product_name: 示例水杯
                          mac_code: DEMO000001-DEMO-B001-WATERCUP
                          switch_prologue: 0
                          version: 1.0.1
                          new_version: 1.0.2
                          can_upgrade: true
                          upgrade_reason: 修复已知问题
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example:
                          -
                            mac_id: 1
                            serial_code: DEMO000001
                            batch_code: B001
                            proudct_code: WATERCUP
                            product_name: 示例水杯
                            mac_code: DEMO000001-DEMO-B001-WATERCUP
                            switch_prologue: 0
                            version: 1.0.1
                            new_version: 1.0.2
                            can_upgrade: true
                            upgrade_reason: 修复已知问题
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            mac_id:
                              type: integer
                              example: 1
                            serial_code:
                              type: string
                              example: DEMO000001
                            batch_code:
                              type: string
                              example: B001
                            proudct_code:
                              type: string
                              example: WATERCUP
                            product_name:
                              type: string
                              example: 示例水杯
                            mac_code:
                              type: string
                              example: DEMO000001-DEMO-B001-WATERCUP
                            switch_prologue:
                              type: integer
                              example: 0
                            version:
                              type: string
                              example: 1.0.1
                            new_version:
                              type: string
                              example: 1.0.2
                            can_upgrade:
                              type: boolean
                              example: true
                            upgrade_reason:
                              type: string
                              example: 修复已知问题
                  -
                    description: 业务失败：未找到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 未找到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 未找到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
  /openapi/user/startup/media/ups:
    post:
      summary: 上传用户开机媒体
      operationId: post_openapi_user_startup_media_ups
      description: 'multipart/form-data 上传并配置指定绑定设备的开机媒体。type=1 图片≤5 MiB，type=2 视频≤10 MiB；统一 MIME 允许 jpeg/png/jpg/mp4/mov。mac_id 是数据库 ID，不是设备编码。响应 data 为当前实现拼出的地址。无绑定 errType=40001；当前用户不存在分支调用未定义 fail 方法，可能返回 HTTP 500，不能依赖统一业务包装。生成文档不执行上传。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: 'http://localhost:8000/storage/demo.jpg'
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: string
                        example: 'http://localhost:8000/storage/demo.jpg'
                        description: '媒体地址字符串，按当前 asset 拼接结果返回。'
                  -
                    description: 业务失败：设备未绑定
                    type: object
                    example:
                      errorCode: 1
                      message: 设备未绑定
                      errType: 40001
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备未绑定
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: integer
                        example: 40001
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：图片大小不能超过5MB
                    type: object
                    example:
                      errorCode: 1
                      message: 图片大小不能超过5MB
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 图片大小不能超过5MB
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                media:
                  type: string
                  format: binary
                  description: '媒体文件；图片≤5 MiB，视频≤10 MiB。'
                type:
                  type: integer
                  description: '1 图片、2 视频。'
                  example: 1
                  enum:
                    - 1
                    - 2
                mac_id:
                  type: integer
                  description: '已经绑定该用户的数据库设备 ID。'
                  example: 1
              required:
                - account
                - media
                - type
                - mac_id
  /openapi/work/bind-to-devices:
    patch:
      summary: 批量绑定智能体到设备
      operationId: patch_openapi_work_bind_to_devices
      description: '只更新 account 已绑定且包含在 mac_id 中的设备；mac_id 支持正整数数组、JSON 数组字符串或单个 ID，重复 ID 去重。任一设备不存在或不属于用户时整批拒绝，不更新匹配子集。检查作品、音色、克隆有效期及会员权限；timbre_id 可空。配置写入设备实际读取的 MAC 分库 Hash，保留 IMEI、语言等其他字段；缓存失败返回业务失败并回滚数据库，已写缓存尽力补偿，持续 Redis 故障时需重试或核对配置。成功保留 code=200，并返回 data 设备数组（mac_id、mac_code、works_id）及 total；表示服务端配置更新，不代表设备已应用。errType：40001 无绑定、40002 高级模型会员、40003 情感会员、40004 音色会员、40005 作品不存在、40006 音色不存在、40007 默认音色不存在、40008 克隆过期，执行异常为 500（仍是 errorCode=1）。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          mac_id: 1
                          mac_code: DEMO000001-DEMO-B001-WATERCUP
                          works_id: 7
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            mac_id: 1
                            mac_code: DEMO000001-DEMO-B001-WATERCUP
                            works_id: 7
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            mac_id:
                              type: integer
                              example: 1
                            mac_code:
                              type: string
                              example: DEMO000001-DEMO-B001-WATERCUP
                            works_id:
                              type: integer
                              example: 7
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：未找到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 未找到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 未找到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：设备未绑定
                    type: object
                    example:
                      errorCode: 1
                      message: 设备未绑定
                      errType: 40001
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备未绑定
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: integer
                        example: 40001
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：作品不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 作品不存在
                      errType: 40005
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 作品不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: integer
                        example: 40005
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：音色不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 音色不存在
                      errType: 40006
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 音色不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: integer
                        example: 40006
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：设备配置更新失败，请重试
                    type: object
                    example:
                      errorCode: 1
                      message: 设备配置更新失败，请重试
                      errType: 500
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备配置更新失败，请重试
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: integer
                        example: 500
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                works_id:
                  type: integer
                  description: '目标智能体 ID，整数 ≥1。'
                  example: 7
                timbre_id:
                  type: integer
                  description: '可选覆盖音色 ID；null 或不传时使用智能体默认音色。'
                  example: null
                mac_id:
                  type: array
                  description: '数据库设备 ID 数组；也兼容单 ID 或 JSON 数组字符串。'
                  example:
                    - 1
                    - 2
                  items:
                    type: integer
              required:
                - account
                - works_id
                - mac_id
  /openapi/user/info/up:
    post:
      summary: 更新用户信息
      operationId: post_openapi_user_info_up
      description: '更新 account 对应用户资料并同步用户缓存，仅提交需要修改的字段。未传字段保留；gender 仅接受 1/2，年龄 age 当前未独立校验。即使无可更新字段也可能返回成功。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：未找到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 未找到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 未找到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: 历史错误响应：姓名不能超过4个字符
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 姓名不能超过4个字符
                  code: 400
                properties:
                  message:
                    type: string
                    example: 姓名不能超过4个字符
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 400
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '02 用户与权益'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                gender:
                  type: integer
                  description: '1 男、2 女。'
                  example: null
                  enum:
                    - 1
                    - 2
                occupation:
                  type: string
                  description: '职业，最长 64 字符。'
                  example: null
                hobby:
                  type: string
                  description: '爱好，最长 64 字符。'
                  example: null
                name:
                  type: string
                  description: '姓名，最长 4 字符。'
                  example: null
                age:
                  type: integer
                  description: 年龄；当前无服务端范围校验。
                  example: null
                city:
                  type: string
                  description: '城市，最长 64 字符。'
                  example: null
                province:
                  type: string
                  description: '省份，最长 64 字符。'
                  example: null
                district:
                  type: string
                  description: '区县，最长 64 字符。'
                  example: null
              required:
                - account
  /openapi/language/list:
    get:
      summary: 获取语言列表
      operationId: get_openapi_language_list
      description: '获取启用的语言配置，不需要 account。按 sort 降序、id 升序；返回项 code 用作 set/language 的 language，不应传名称。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        -
                          id: 1
                          code: zh-CN
                          name: 中文（简体）
                          status: 1
                          sort: 100
                          create_at: '2026-10-20 10:00:00'
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example:
                          -
                            id: 1
                            code: zh-CN
                            name: 中文（简体）
                            status: 1
                            sort: 100
                            create_at: '2026-10-20 10:00:00'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            code:
                              type: string
                              example: zh-CN
                            name:
                              type: string
                              example: 中文（简体）
                            status:
                              type: integer
                              example: 1
                            sort:
                              type: integer
                              example: 100
                            create_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '03 用户设置'
  /openapi/set/language:
    post:
      summary: 设置用户设备语言
      operationId: post_openapi_set_language
      description: '对当前接入方用户选择该语言热度最高的公开、已发布智能体，并更新其所有绑定设备缓存。language 默认 zh-CN；写入设备时变为 zh。成功不代表设备收到或应用配置。无匹配智能体时仍 errorCode=0、data=null，不视为已经完成切换。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        works_id: 7
                        model_id: 3
                        timbre_id: 100
                        model_code: demo-model
                        model_free: 1
                        timbre_code: demo_voice
                        timbre_platform: volcengine
                        mac_language: zh
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          works_id:
                            type: integer
                            example: 7
                            description: '智能体 ID；缓存读取时可能是字符串。'
                          model_id:
                            type: integer
                            example: 3
                            description: '模型 ID。'
                          timbre_id:
                            type: integer
                            example: 100
                            description: '音色 ID。'
                          model_code:
                            type: string
                            example: demo-model
                            description: 模型运行标识。
                          model_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费，收费模型通常需要有效会员。'
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          mac_language:
                            type: string
                            example: zh
                            description: '设备语言；zh-CN 写入设备配置时可转换为 zh。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: null
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: string
                        example: null
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                  -
                    description: 业务失败：账号不存在或不属于当前接入方！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '03 用户设置'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                language:
                  type: string
                  description: 'language/list 返回的 code，默认 zh-CN。'
                  example: zh-CN
              required:
                - account
  /openapi/user/reports/up:
    post:
      summary: 更新轻语评测配置
      operationId: post_openapi_user_reports_up
      description: '更新当前接入方用户的评测开关及缓存；不传 user_reports_is_open 默认 2。该转调方法没有业务值枚举校验，调用方按 1 开启、2 关闭传入。成功只表示配置处理成功，不会立即生成评测报告。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：账号不存在或不属于当前接入方！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '业务失败：Redis update failed'
                    type: object
                    example:
                      errorCode: 1
                      message: 'Redis update failed'
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 'Redis update failed'
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '03 用户设置'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                user_reports_is_open:
                  type: integer
                  description: '1 开启、2 关闭；默认 2。'
                  example: 2
              required:
                - account
  /openapi/user/reports/info:
    get:
      summary: 获取轻语评测配置
      operationId: get_openapi_user_reports_info
      description: '查询 week 周报或 month 月报，默认 week；按 Accept-Language 取同语种报告，不回退中文。优先上周/上月，无报告则回退最近同语种同类型；仍没有时 reports_info=null。当前实现回退后排名查询时间会更新，但返回 startDate/endDate 保留最初时间；chat_info 当前硬编码统计用户 1，且 music_count 被闹钟次数覆盖，不能据此判断当前用户真实统计。这些是现有行为，文档不改变业务代码。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: query
          name: type
          description: 'week 周报、month 月报；默认 week，其他值也走周报。'
          example: week
          required: false
          schema:
            type: string
            description: 'week 周报、month 月报；默认 week，其他值也走周报。'
            example: week
            enum:
              - week
              - month
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        startDate: '2026-10-12 00:00:00'
                        endDate: '2026-10-18 23:59:59'
                        reports_info:
                          id: 1
                          user_id: 123
                          chat_id: 1
                          report_date: '2026-10-12'
                          type: 1
                          report_language: zh-CN
                          total_score: 80
                          emotion_report: 本周期情绪平稳。
                          behavior_analysis: 能够主动表达。
                          suggestion_measures: 保持规律交流。
                          emotion_scores: '{"positive":80}'
                          ability_scores:
                            expression: 80
                          communication_dimensions:
                            initiative: 80
                          radar_advantage_zone: 表达
                          radar_development_zone: 专注
                          radar_overall_profile: 整体表现平稳。
                          focus_analysis: 能够持续关注话题。
                          thinking_analysis: 能提出问题。
                          expression_analysis: 表达清晰。
                          resilience_analysis: 愿意尝试。
                          execution_analysis: 行动积极。
                          comprehensive_suggestion: 多进行开放式交流。
                          disclaimer: 仅供日常参考。
                          created_at: '2026-10-20 10:00:00'
                          updated_at: '2026-10-20 10:00:00'
                        overall_score_rank: 1
                        overall_score_rank_percentage: 50
                        chat_info:
                          chat_count: 12
                          music_count: 1
                          weather_count: 1
                          other_count: 0
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          startDate:
                            type: string
                            example: '2026-10-12 00:00:00'
                            description: 报告查询起始日期时间；最近报告回退行为见接口说明。
                          endDate:
                            type: string
                            example: '2026-10-18 23:59:59'
                            description: 报告查询结束日期时间。
                          reports_info:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                                description: '记录 ID，具体对应实体见接口说明。'
                              user_id:
                                type: integer
                                example: 123
                                description: '平台用户数字 ID，不是接入方 account。'
                              chat_id:
                                type: integer
                                example: 1
                                description: '对话记录 ID。'
                              report_date:
                                type: string
                                example: '2026-10-12'
                                description: 报告周期基准日期。
                              type:
                                type: integer
                                example: 1
                                description: 业务类型，具体枚举以接口说明为准。
                              report_language:
                                type: string
                                example: zh-CN
                                description: 存储报告的语言，空值时可隐藏此字段。
                              total_score:
                                type: integer
                                example: 80
                                description: 报告综合得分。
                              emotion_report:
                                type: string
                                example: 本周期情绪平稳。
                                description: 情绪报告正文。
                              behavior_analysis:
                                type: string
                                example: 能够主动表达。
                                description: 行为分析。
                              suggestion_measures:
                                type: string
                                example: 保持规律交流。
                                description: 建议措施。
                              emotion_scores:
                                type: string
                                example: '{"positive":80}'
                                description: '情绪得分的存储 JSON 字符串。'
                              ability_scores:
                                type: object
                                properties:
                                  expression:
                                    type: integer
                                    example: 80
                                description: '能力维度得分对象；维度键由报告生成，非空时解码 JSON，空时可能为空字符串。'
                              communication_dimensions:
                                type: object
                                properties:
                                  initiative:
                                    type: integer
                                    example: 80
                                description: '沟通维度对象，维度键由报告生成，非空时解码 JSON。'
                              radar_advantage_zone:
                                type: string
                                example: 表达
                                description: 雷达优势区说明。
                              radar_development_zone:
                                type: string
                                example: 专注
                                description: 雷达发展区说明。
                              radar_overall_profile:
                                type: string
                                example: 整体表现平稳。
                                description: 雷达整体画像。
                              focus_analysis:
                                type: string
                                example: 能够持续关注话题。
                                description: 专注力分析。
                              thinking_analysis:
                                type: string
                                example: 能提出问题。
                                description: 思考能力分析。
                              expression_analysis:
                                type: string
                                example: 表达清晰。
                                description: 表达能力分析。
                              resilience_analysis:
                                type: string
                                example: 愿意尝试。
                                description: 韧性分析。
                              execution_analysis:
                                type: string
                                example: 行动积极。
                                description: 执行力分析。
                              comprehensive_suggestion:
                                type: string
                                example: 多进行开放式交流。
                                description: 综合建议。
                              disclaimer:
                                type: string
                                example: 仅供日常参考。
                                description: 报告使用说明或免责声明。
                              created_at:
                                type: string
                                example: '2026-10-20 10:00:00'
                                description: 创建日期时间。
                              updated_at:
                                type: string
                                example: '2026-10-20 10:00:00'
                                description: 更新日期时间。
                            description: '报告对象或 null。模型包含 emotion_report、behavior_analysis、suggestion_measures、emotion_scores、ability_scores、communication_dimensions、radar_advantage_zone、radar_development_zone、radar_overall_profile、focus_analysis、thinking_analysis、expression_analysis、resilience_analysis、execution_analysis、comprehensive_suggestion、disclaimer、report_language、report_date、type、user_id、chat_id 及时间字段。ability_scores/communication_dimensions 非空时 JSON 解码，空时可能是空字符串；report_language 为空时隐藏。'
                            nullable: true
                          overall_score_rank:
                            type: integer
                            example: 1
                            description: '当前报告周期与语言下的综合排名，缺省 0。'
                          overall_score_rank_percentage:
                            type: integer
                            example: 50
                            description: 超过其他用户的百分比数值。
                          chat_info:
                            type: object
                            properties:
                              chat_count:
                                type: integer
                                example: 12
                                description: 大模型对话次数；报告接口存在历史统计口径，详见说明。
                              music_count:
                                type: integer
                                example: 1
                                description: 当前代码实际被闹钟次数覆盖，不可按音乐次数使用。
                              weather_count:
                                type: integer
                                example: 1
                                description: 天气次数。
                              other_count:
                                type: integer
                                example: 0
                                description: 其他对话次数。
                            description: 报告附带的次数统计，现有口径限制见接口说明。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        startDate: '2026-10-12 00:00:00'
                        endDate: '2026-10-18 23:59:59'
                        reports_info: null
                        overall_score_rank: 0
                        overall_score_rank_percentage: 0
                        chat_info:
                          chat_count: 0
                          music_count: 0
                          weather_count: 0
                          other_count: 0
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          startDate:
                            type: string
                            example: '2026-10-12 00:00:00'
                            description: 报告查询起始日期时间；最近报告回退行为见接口说明。
                          endDate:
                            type: string
                            example: '2026-10-18 23:59:59'
                            description: 报告查询结束日期时间。
                          reports_info:
                            type: string
                            example: null
                            description: '报告对象或 null。模型包含 emotion_report、behavior_analysis、suggestion_measures、emotion_scores、ability_scores、communication_dimensions、radar_advantage_zone、radar_development_zone、radar_overall_profile、focus_analysis、thinking_analysis、expression_analysis、resilience_analysis、execution_analysis、comprehensive_suggestion、disclaimer、report_language、report_date、type、user_id、chat_id 及时间字段。ability_scores/communication_dimensions 非空时 JSON 解码，空时可能是空字符串；report_language 为空时隐藏。'
                            nullable: true
                          overall_score_rank:
                            type: integer
                            example: 0
                            description: '当前报告周期与语言下的综合排名，缺省 0。'
                          overall_score_rank_percentage:
                            type: integer
                            example: 0
                            description: 超过其他用户的百分比数值。
                          chat_info:
                            type: object
                            properties:
                              chat_count:
                                type: integer
                                example: 0
                                description: 大模型对话次数；报告接口存在历史统计口径，详见说明。
                              music_count:
                                type: integer
                                example: 0
                                description: 当前代码实际被闹钟次数覆盖，不可按音乐次数使用。
                              weather_count:
                                type: integer
                                example: 0
                                description: 天气次数。
                              other_count:
                                type: integer
                                example: 0
                                description: 其他对话次数。
                            description: 报告附带的次数统计，现有口径限制见接口说明。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：账号不存在或不属于当前接入方！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '03 用户设置'
  /openapi/user/is_minor/up:
    post:
      summary: 更新未成年模式配置
      operationId: post_openapi_user_is_minor_up
      description: '更新当前接入方用户的未成年模式及所有绑定设备配置。is_minor 必须 1/2；其余开关未传会转整数 0 并覆盖缓存，不是局部更新。若传 minor_password，在关闭或部分开启场景会验证已保存密码；未传时现实现不触发密码校验。本接口不设置密码。设备配置成功不代表硬件已生效；有绑定设备时资料表轮数历史代码固定写 50/1，而缓存使用入参。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        is_minor: 1
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          is_minor:
                            type: integer
                            example: 1
                            description: '未成年模式：1 开启、2 关闭。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：未成年开关仅支持1(开启)或2(关闭)
                    type: object
                    example:
                      errorCode: 1
                      message: 未成年开关仅支持1(开启)或2(关闭)
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 未成年开关仅支持1(开启)或2(关闭)
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：未设置未成年密码，请先设置
                    type: object
                    example:
                      errorCode: 1
                      message: 未设置未成年密码，请先设置
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 未设置未成年密码，请先设置
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：未成年密码错误
                    type: object
                    example:
                      errorCode: 1
                      message: 未成年密码错误
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 未成年密码错误
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '03 用户设置'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                is_minor:
                  type: integer
                  description: '1 开启、2 关闭。'
                  example: 1
                  enum:
                    - 1
                    - 2
                minor_password:
                  type: string
                  description: 可选已设置的未成年密码；传入时按场景校验，不用于设置。
                  example: null
                chat_limit_round:
                  type: integer
                  description: '对话轮数，未传转为 0；当前未校验范围。'
                  example: 50
                limit_round_is_open:
                  type: integer
                  description: '轮数限制开关，业务值 1 开启、2 关闭；未传写 0。'
                  example: 2
                game_anti_addiction_is_open:
                  type: integer
                  description: '游戏防沉迷开关，1 开启、2 关闭；未传写 0。'
                  example: 2
                usage_duration_prompt_is_open:
                  type: integer
                  description: '设备使用时长提醒，1 开启、2 关闭；未传写 0。'
                  example: 2
                app_usage_duration_prompt_is_open:
                  type: integer
                  description: 'App 使用时长提醒，1 开启、2 关闭；未传写 0。'
                  example: 2
              required:
                - account
                - is_minor
  /openapi/user/is_minor/info:
    get:
      summary: 获取未成年模式配置
      operationId: get_openapi_user_is_minor_info
      description: '只返回未成年模式六项配置白名单，缺失时开关默认 2、轮数默认 0。不会向开放平台返回监护人手机号、密码或购买资格字段。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        is_minor: 2
                        app_usage_duration_prompt_is_open: 2
                        chat_limit_round: 0
                        limit_round_is_open: 2
                        game_anti_addiction_is_open: 2
                        usage_duration_prompt_is_open: 2
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          is_minor:
                            type: integer
                            example: 2
                            description: '未成年模式：1 开启、2 关闭。'
                          app_usage_duration_prompt_is_open:
                            type: integer
                            example: 2
                            description: 'App 时长提醒：1 开启、2 关闭，更新未传时可能写 0。'
                          chat_limit_round:
                            type: integer
                            example: 0
                            description: 对话轮数配置。
                          limit_round_is_open:
                            type: integer
                            example: 2
                            description: '轮数限制开关：1 开启、2 关闭。'
                          game_anti_addiction_is_open:
                            type: integer
                            example: 2
                            description: '游戏防沉迷开关：1 开启、2 关闭。'
                          usage_duration_prompt_is_open:
                            type: integer
                            example: 2
                            description: '设备时长提醒：1 开启、2 关闭。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：账号不存在或不属于当前接入方！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '03 用户设置'
  /openapi/mac/user:
    put:
      summary: 绑定设备与用户
      operationId: put_openapi_mac_user
      description: '绑定或重新绑定设备到用户，支持一个用户多台设备。同一 mac_id 只保留一个绑定用户，重复绑定会更新用户和默认智能体。未导入设备按编码解析公司/批次，检查授权和批次数量；默认智能体来自产品配置，否则默认 7。会同步 SIM 卡归属、执行绑定赠送权益并更新设备配置。imei/devideid 未传时写空字符串；语言非 zh 开头时地区按国外处理。成功表示服务端绑定处理完成，不表示硬件应用完成。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：设备未授权，请联系客服(001)！
                    type: object
                    example:
                      message: 设备未授权，请联系客服(001)！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 设备未授权，请联系客服(001)！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：已超过批次数量！
                    type: object
                    example:
                      message: 已超过批次数量！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 已超过批次数量！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：账号不存在或手机号存在多个历史账号！
                    type: object
                    example:
                      message: 账号不存在或手机号存在多个历史账号！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 账号不存在或手机号存在多个历史账号！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '04 设备与绑定'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
                  example: DEMO000001-DEMO-B001-WATERCUP
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                imei:
                  type: string
                  description: '设备 IMEI，可选。'
                  example: null
                devideid:
                  type: string
                  description: '设备 ID，保留历史拼写 devideid。'
                  example: null
                mac_language:
                  type: string
                  description: '设备语言代码，例如 zh-CN/en；影响地区判断。'
                  example: zh-CN
                mac_timezone:
                  type: string
                  description: '设备时区，例如 Asia/Shanghai。'
                  example: Asia/Shanghai
              required:
                - mac
                - account
  /openapi/get/model/list:
    get:
      summary: 获取模型列表
      operationId: get_openapi_get_model_list
      description: '获取当前 Token 所属公司配置的模型列表，只返回 model_status=1，按 model_sort 降序。无业务参数。返回原始模型字段；密钥池不在返回范围，列表不代表当前用户已购买收费模型权益。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          model_id: 3
                          model_code: demo-model
                          model_name: 示例模型
                          model_status: 1
                          model_created_at: '2026-10-20 10:00:00'
                          model_avatar: ''
                          model_show: 1
                          model_free: 1
                          model_sort: 1
                          language: zh-CN
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            model_id: 3
                            model_code: demo-model
                            model_name: 示例模型
                            model_status: 1
                            model_created_at: '2026-10-20 10:00:00'
                            model_avatar: ''
                            model_show: 1
                            model_free: 1
                            model_sort: 1
                            language: zh-CN
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            model_id:
                              type: integer
                              example: 3
                            model_code:
                              type: string
                              example: demo-model
                            model_name:
                              type: string
                              example: 示例模型
                            model_status:
                              type: integer
                              example: 1
                            model_created_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            model_avatar:
                              type: string
                              example: ''
                            model_show:
                              type: integer
                              example: 1
                            model_free:
                              type: integer
                              example: 1
                            model_sort:
                              type: integer
                              example: 1
                            language:
                              type: string
                              example: zh-CN
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '04 设备与绑定'
  '/openapi/mac/works/{mac}':
    get:
      summary: 获取设备智能体列表
      operationId: get_openapi_mac_works_mac_
      description: 'mac 为路径参数，不放查询或请求体。要求设备已授权且已绑定，按该设备公司配置的模型与分类返回公开、审核通过的智能体，仅含 works_id、works_name。路径匹配要求大写字母/数字开头，后续为字母数字下划线或短横线。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          works_id: 7
                          works_name: 示例助手
                      total: 1
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            works_id: 7
                            works_name: 示例助手
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            works_id:
                              type: integer
                              example: 7
                            works_name:
                              type: string
                              example: 示例助手
                      total:
                        type: integer
                        example: 1
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：设备未授权，请联系客服！
                    type: object
                    example:
                      message: 设备未授权，请联系客服！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 设备未授权，请联系客服！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：请先绑定设备！
                    type: object
                    example:
                      message: 请先绑定设备！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 请先绑定设备！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '04 设备与绑定'
    parameters:
      -
        in: path
        name: mac
        description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
        example: DEMO000001-DEMO-B001-WATERCUP
        required: true
        schema:
          type: string
  '/openapi/mac/works/bind/{mac}':
    post:
      summary: 绑定设备智能体
      operationId: post_openapi_mac_works_bind_mac_
      description: 'mac 为路径参数，works_id 放请求体。要求设备已授权且已绑定。更新该设备绑定的智能体和模型/音色配置缓存；此入口没有复用 user/work 入口的全部 VIP 检查，不能假设不同入口校验相同。当前未单独处理作品不存在空值，应从列表中选择有效 ID。成功不代表设备已应用。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
        400:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 历史错误响应：设备未授权，请联系客服！
                    type: object
                    example:
                      message: 设备未授权，请联系客服！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 设备未授权，请联系客服！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 历史错误响应：请先绑定设备！
                    type: object
                    example:
                      message: 请先绑定设备！
                      code: 400
                    properties:
                      message:
                        type: string
                        example: 请先绑定设备！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '04 设备与绑定'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                works_id:
                  type: integer
                  description: '智能体 ID，整数 ≥1。'
                  example: 7
              required:
                - works_id
    parameters:
      -
        in: path
        name: mac
        description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
        example: DEMO000001-DEMO-B001-WATERCUP
        required: true
        schema:
          type: string
  /openapi/get/mac/works:
    get:
      summary: 获取设备当前智能体
      operationId: get_openapi_get_mac_works
      description: '从设备缓存读取当前 works_id。无数据库绑定校验，未配置或缓存缺失时字段可能为空值/false；缓存数字也可能是字符串。注意本接口 mac 为查询参数。'
      parameters:
        -
          in: query
          name: mac
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        works_id: '7'
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          works_id:
                            type: string
                            example: '7'
                            description: '智能体 ID；缓存读取时可能是字符串。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '04 设备与绑定'
  /openapi/work/mine:
    get:
      summary: 获取我的智能体
      operationId: get_openapi_work_mine
      description: '获取 account 用户创建的智能体，按 works_id 降序，使用 Laravel 标准分页（data.data 为列表，data.total 为总数）。关联 user/model/timbre 可为空，collection_count 为收藏关联计数。空简介规范为空字符串，头像按存储地址规则转换。works_authority 可筛选公开/私密。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: query
          name: mine_name
          description: '智能体名称模糊搜索；少数既有账号兼容 ID 搜索。'
          example: null
          required: false
          schema:
            type: string
            description: '智能体名称模糊搜索；少数既有账号兼容 ID 搜索。'
            example: null
        -
          in: query
          name: works_authority
          description: '1 公开、2 私密；不传不筛选。'
          example: null
          required: false
          schema:
            type: integer
            description: '1 公开、2 私密；不传不筛选。'
            example: null
            enum:
              - 1
              - 2
        -
          in: query
          name: page
          description: '页码，默认 1。'
          example: 1
          required: false
          schema:
            type: integer
            description: '页码，默认 1。'
            example: 1
        -
          in: query
          name: perPage
          description: '每页数量，默认 20。'
          example: 20
          required: false
          schema:
            type: integer
            description: '每页数量，默认 20。'
            example: 20
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        current_page: 1
                        data:
                          -
                            works_id: 7
                            user_id: 123
                            model_id: 3
                            timbre_id: 100
                            works_name: 示例助手
                            works_avatar: ''
                            works_system: 你是一个耐心的助手。
                            works_authority: 1
                            works_status: 2
                            works_cause: ''
                            works_star: 10
                            works_created_at: '2026-10-20 10:00:00'
                            works_updated_at: '2026-10-20 10:00:00'
                            works_intro: 帮助回答日常问题
                            works_default: 2
                            wc_id: 1
                            works_sort: 1
                            works_extension: ''
                            language: zh-CN
                            user:
                              user_id: 123
                              user_account: platform_demo_001
                              user_phone: ''
                              user_nickname: 示例用户
                              user_avatar: ''
                            model:
                              model_id: 3
                              model_code: demo-model
                              model_name: 示例模型
                              model_free: 1
                            timbre:
                              timbre_id: 100
                              timbre_code: demo_voice
                              timbre_name: 示例音色
                              timbre_gender: 1
                              timbre_age_group: 3
                              timbre_tag: 自然
                              timbre_free: 1
                              timbre_platform: volcengine
                              timbre_avatar: ''
                              timbre_user_id: 0
                              timbre_expire_at: 0
                            collection_count: 0
                        first_page_url: 'http://localhost:8000/?page=1'
                        from: 1
                        last_page: 1
                        last_page_url: 'http://localhost:8000/?page=1'
                        links:
                          -
                            url: null
                            label: 上一页
                            active: false
                          -
                            url: 'http://localhost:8000/?page=1'
                            label: '1'
                            active: true
                        next_page_url: null
                        path: 'http://localhost:8000/'
                        per_page: 20
                        prev_page_url: null
                        to: 1
                        total: 1
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                            description: 当前页码。
                          data:
                            type: array
                            example:
                              -
                                works_id: 7
                                user_id: 123
                                model_id: 3
                                timbre_id: 100
                                works_name: 示例助手
                                works_avatar: ''
                                works_system: 你是一个耐心的助手。
                                works_authority: 1
                                works_status: 2
                                works_cause: ''
                                works_star: 10
                                works_created_at: '2026-10-20 10:00:00'
                                works_updated_at: '2026-10-20 10:00:00'
                                works_intro: 帮助回答日常问题
                                works_default: 2
                                wc_id: 1
                                works_sort: 1
                                works_extension: ''
                                language: zh-CN
                                user:
                                  user_id: 123
                                  user_account: platform_demo_001
                                  user_phone: ''
                                  user_nickname: 示例用户
                                  user_avatar: ''
                                model:
                                  model_id: 3
                                  model_code: demo-model
                                  model_name: 示例模型
                                  model_free: 1
                                timbre:
                                  timbre_id: 100
                                  timbre_code: demo_voice
                                  timbre_name: 示例音色
                                  timbre_gender: 1
                                  timbre_age_group: 3
                                  timbre_tag: 自然
                                  timbre_free: 1
                                  timbre_platform: volcengine
                                  timbre_avatar: ''
                                  timbre_user_id: 0
                                  timbre_expire_at: 0
                                collection_count: 0
                            description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                            items:
                              type: object
                              properties:
                                works_id:
                                  type: integer
                                  example: 7
                                user_id:
                                  type: integer
                                  example: 123
                                model_id:
                                  type: integer
                                  example: 3
                                timbre_id:
                                  type: integer
                                  example: 100
                                works_name:
                                  type: string
                                  example: 示例助手
                                works_avatar:
                                  type: string
                                  example: ''
                                works_system:
                                  type: string
                                  example: 你是一个耐心的助手。
                                works_authority:
                                  type: integer
                                  example: 1
                                works_status:
                                  type: integer
                                  example: 2
                                works_cause:
                                  type: string
                                  example: ''
                                works_star:
                                  type: integer
                                  example: 10
                                works_created_at:
                                  type: string
                                  example: '2026-10-20 10:00:00'
                                works_updated_at:
                                  type: string
                                  example: '2026-10-20 10:00:00'
                                works_intro:
                                  type: string
                                  example: 帮助回答日常问题
                                works_default:
                                  type: integer
                                  example: 2
                                wc_id:
                                  type: integer
                                  example: 1
                                works_sort:
                                  type: integer
                                  example: 1
                                works_extension:
                                  type: string
                                  example: ''
                                language:
                                  type: string
                                  example: zh-CN
                                user:
                                  type: object
                                  properties:
                                    user_id:
                                      type: integer
                                      example: 123
                                    user_account:
                                      type: string
                                      example: platform_demo_001
                                    user_phone:
                                      type: string
                                      example: ''
                                    user_nickname:
                                      type: string
                                      example: 示例用户
                                    user_avatar:
                                      type: string
                                      example: ''
                                model:
                                  type: object
                                  properties:
                                    model_id:
                                      type: integer
                                      example: 3
                                    model_code:
                                      type: string
                                      example: demo-model
                                    model_name:
                                      type: string
                                      example: 示例模型
                                    model_free:
                                      type: integer
                                      example: 1
                                timbre:
                                  type: object
                                  properties:
                                    timbre_id:
                                      type: integer
                                      example: 100
                                    timbre_code:
                                      type: string
                                      example: demo_voice
                                    timbre_name:
                                      type: string
                                      example: 示例音色
                                    timbre_gender:
                                      type: integer
                                      example: 1
                                    timbre_age_group:
                                      type: integer
                                      example: 3
                                    timbre_tag:
                                      type: string
                                      example: 自然
                                    timbre_free:
                                      type: integer
                                      example: 1
                                    timbre_platform:
                                      type: string
                                      example: volcengine
                                    timbre_avatar:
                                      type: string
                                      example: ''
                                    timbre_user_id:
                                      type: integer
                                      example: 0
                                    timbre_expire_at:
                                      type: integer
                                      example: 0
                                collection_count:
                                  type: integer
                                  example: 0
                          first_page_url:
                            type: string
                            example: 'http://localhost:8000/?page=1'
                            description: 第一页链接；示例地址仅演示结构。
                          from:
                            type: integer
                            example: 1
                            description: '当前页起始序号；空页可为 null。'
                          last_page:
                            type: integer
                            example: 1
                            description: 最后一页页码。
                          last_page_url:
                            type: string
                            example: 'http://localhost:8000/?page=1'
                            description: 最后一页链接。
                          links:
                            type: array
                            example:
                              -
                                url: null
                                label: 上一页
                                active: false
                              -
                                url: 'http://localhost:8000/?page=1'
                                label: '1'
                                active: true
                            description: 分页链接数组。
                            items:
                              type: object
                              properties:
                                url:
                                  type: string
                                  example: null
                                  nullable: true
                                label:
                                  type: string
                                  example: 上一页
                                active:
                                  type: boolean
                                  example: false
                          next_page_url:
                            type: string
                            example: null
                            description: '下一页链接，无下一页时为 null。'
                            nullable: true
                          path:
                            type: string
                            example: 'http://localhost:8000/'
                            description: 分页接口基础地址。
                          per_page:
                            type: integer
                            example: 20
                            description: 每页条数。
                          prev_page_url:
                            type: string
                            example: null
                            description: '上一页链接，无上一页时为 null。'
                            nullable: true
                          to:
                            type: integer
                            example: 1
                            description: '当前页结束序号；空页可为 null。'
                          total:
                            type: integer
                            example: 1
                            description: '记录总数；非列表 successData 包装默认 0。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '05 智能体'
  /openapi/work/avatar:
    post:
      summary: 上传智能体头像
      operationId: post_openapi_work_avatar
      description: 'multipart/form-data 上传并压缩头像，data 为图片地址字符串，可直接作为 work/add 的 works_avatar。必须通过 Laravel image 校验，控制器扩展名白名单 JPG/JPEG/PNG/GIF/SVG；最终还受图像解码能力限制。没有额外业务大小上限，受 PHP 和服务器上传配置约束。浏览器自动设置 multipart boundary。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: 'https://example.com/demo-avatar.jpg'
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: string
                        example: 'https://example.com/demo-avatar.jpg'
                        description: '压缩后的图片地址，可用于 works_avatar。'
                  -
                    description: 业务失败：不支持该格式，请重新上传！
                    type: object
                    example:
                      errorCode: 1
                      message: 不支持该格式，请重新上传！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 不支持该格式，请重新上传！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
        422:
          description: 'Laravel 参数校验失败（Accept: application/json，提示文本随语言变化）'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 请选择图片上传！
                  errors:
                    image:
                      - 请选择图片上传！
                properties:
                  message:
                    type: string
                    example: 请选择图片上传！
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  errors:
                    type: object
                    properties:
                      image:
                        type: array
                        example:
                          - 请选择图片上传！
                        items:
                          type: string
                    description: 'Laravel 参数错误字典，键为参数名，值为错误提示数组；HTTP 422，提示文本随语言变化。'
      tags:
        - '05 智能体'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: 图片文件，必填。
              required:
                - image
  /openapi/drink/statistics:
    post:
      summary: 获取饮水统计
      operationId: post_openapi_drink_statistics
      description: '按 account 查询饮水数据。type 默认 day：day 为 24 小时、week 为一周 7 天、month 为每一天、year 为 12 个月；未知 type 当前回退 day。date 不传为今天，使用 Carbon 解析；chart_data 为各时间段的摄入量。total_intake 单位毫升；recent_drink_count 为基准日期当天记录次数。target_days 来自过去 365 天按天分组、总量≥2000毫升的计数查询，不是连续达标天数，也不读取用户设置的饮水目标。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: '成功（chart_data 展示一个时间段，实际按周期补齐）'
                    type: object
                    example:
                      code: 200
                      message: 获取成功
                      data:
                        total_intake: 250
                        chart_data:
                          -
                            time_key: '10'
                            value: 250
                        recent_drink_count: 1
                        target_days: 0
                    properties:
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: 获取成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          total_intake:
                            type: integer
                            example: 250
                            description: 当前周期累计饮水量，单位毫升。
                          chart_data:
                            type: array
                            example:
                              -
                                time_key: '10'
                                value: 250
                            description: 周期内时间段饮水量数组。
                            items:
                              type: object
                              properties:
                                time_key:
                                  type: string
                                  example: '10'
                                value:
                                  type: integer
                                  example: 250
                          recent_drink_count:
                            type: integer
                            example: 1
                            description: 基准日期当天饮水记录次数。
                          target_days:
                            type: integer
                            example: 0
                            description: '过去 365 天按固定每日 2000 毫升阈值查询所得计数，不是连续达标天数。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                  -
                    description: '日期解析失败（HTTP 200）'
                    type: object
                    example:
                      code: 400
                      message: 日期格式错误
                      data: null
                    properties:
                      code:
                        type: integer
                        example: 400
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: 日期格式错误
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: string
                        example: null
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        nullable: true
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '06 饮水管理'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                type:
                  type: string
                  description: 'day/week/month/year，默认 day。'
                  example: day
                  enum:
                    - day
                    - week
                    - month
                    - year
                date:
                  type: string
                  description: '统计基准日期，建议 Y-m-d，默认今天。'
                  example: '2026-10-20'
              required:
                - account
  /openapi/drink/today_statistics:
    get:
      summary: 获取今日饮水量
      operationId: get_openapi_drink_today_statistics
      description: '查询用户今天累计摄入量（毫升）。account 与 mac 都需提供；mac 最后一个短横线段必须为 WATERCUP，其他产品失败。成功返回 water_intake 整数，无记录为 0。当前摄入量按用户汇总，不是只按此台 mac 过滤。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: query
          name: mac
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        water_intake: 250
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          water_intake:
                            type: integer
                            example: 250
                            description: 今天累计饮水量，单位毫升。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
        400:
          description: 历史错误响应：mac不能为空
          content:
            application/json:
              schema:
                type: object
                example:
                  message: mac不能为空
                  code: 400
                properties:
                  message:
                    type: string
                    example: mac不能为空
                    description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  code:
                    type: integer
                    example: 400
                    description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
      tags:
        - '06 饮水管理'
  /openapi/drink/set-drinking-water:
    post:
      summary: 设置饮水目标
      operationId: post_openapi_drink_set_drinking_water
      description: '设置用户每日饮水目标（毫升），未传 water_target 默认 0；当前代码只做整数转换，没有正数或最大值校验。只更新已有用户资料行，无行时不新建但仍可能返回成功。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        water_target: 1500
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          water_target:
                            type: integer
                            example: 1500
                            description: 每日饮水目标，单位毫升。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '06 饮水管理'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                water_target:
                  type: integer
                  description: '每日目标毫升数；省略为 0。'
                  example: 1500
              required:
                - account
  /openapi/chat/log/del:
    post:
      summary: 删除对话记录
      operationId: post_openapi_chat_log_del
      description: '删除 account 用户在 works_id 下的大模型聊天记录（chat_type=0），按历史月份分表执行并记录删除进度。不会删除其他类型记录；清除上下文需另调 chat/context/del。删除可能不可恢复，请勿用真实账号试调。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data: []
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：请选择作品ID！
                    type: object
                    example:
                      errorCode: 1
                      message: 请选择作品ID！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 请选择作品ID！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '07 对话记录'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                works_id:
                  type: integer
                  description: '智能体 ID，整数 ≥1。'
                  example: 7
              required:
                - account
                - works_id
  /openapi/chat/context/del:
    post:
      summary: 清除对话上下文
      operationId: post_openapi_chat_context_del
      description: '清除 account 与 works_id 对应的对话上下文及部分模型会话标识，不删除历史聊天记录。works_id 整数 ≥1。成功表示服务端缓存清理完成。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：请选择作品ID！
                    type: object
                    example:
                      errorCode: 1
                      message: 请选择作品ID！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 请选择作品ID！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '07 对话记录'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                works_id:
                  type: integer
                  description: '智能体 ID，整数 ≥1。'
                  example: 7
              required:
                - account
                - works_id
  /openapi/chat/user/count:
    post:
      summary: 获取用户对话次数统计
      operationId: post_openapi_chat_user_count
      description: '按平台 user_id 统计指定起止时间内的大模型对话次数，支持跨月表；end_time 必须晚于 start_time，格式均为 Y-m-d H:i:s。本接口使用平台数字 ID，不是 account；当前控制器未额外验证 user_id 所属接入方，不能将 Token 认证视为已保证该查询的用户隔离。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        user_id: 123
                        start_time: '2026-10-01 00:00:00'
                        end_time: '2026-10-20 23:59:59'
                        chat_count: 12
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          user_id:
                            type: integer
                            example: 123
                            description: '平台用户数字 ID，不是接入方 account。'
                          start_time:
                            type: string
                            example: '2026-10-01 00:00:00'
                            description: 统计开始时间。
                          end_time:
                            type: string
                            example: '2026-10-20 23:59:59'
                            description: 统计结束时间。
                          chat_count:
                            type: integer
                            example: 12
                            description: 大模型对话次数；报告接口存在历史统计口径，详见说明。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：结束时间必须晚于开始时间
                    type: object
                    example:
                      errorCode: 1
                      message: 结束时间必须晚于开始时间
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 结束时间必须晚于开始时间
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '07 对话记录'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  description: '平台用户 ID，整数 ≥1。'
                  example: 123
                start_time:
                  type: string
                  description: '开始时间，Y-m-d H:i:s。'
                  example: '2026-10-01 00:00:00'
                end_time:
                  type: string
                  description: '结束时间，Y-m-d H:i:s，晚于开始时间。'
                  example: '2026-10-20 23:59:59'
              required:
                - user_id
                - start_time
                - end_time
  /openapi/mac/ota/confirm:
    post:
      summary: 确认设备OTA升级
      operationId: post_openapi_mac_ota_confirm
      description: '确认 account 当前绑定设备的 OTA 升级。mac 必须完整设备编码，new_version 从 user/devices/info 获取，并且仍须匹配服务端当前固件版本。按公司、批次、产品取最新配置，拒绝旧目标版本、同版本和降级。设备尚未上报版本时允许确认，由设备下载接口最终比较。确认写入 Redis DB 2，通知失败仍保留确认，设备主动检查时可以升级。重复请求幂等保存确认，短时间内限制重复通知，失败可立即重试。成功仅表示确认已保存，notification_status=sent 仅表示指令已提交；failed 表示通知失败；throttled 表示近期已尝试通知，等待至少15秒（配置超时更大时相应延长）后可重试。设备离线不阻止确认，不代表升级完成。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        mac: DEMO000001-DEMO-B001-WATERCUP
                        new_version: 1.0.2
                        confirmed: true
                        notification_status: sent
                        notification_message: 升级指令已提交，不代表设备已接收或升级完成
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          mac:
                            type: string
                            example: DEMO000001-DEMO-B001-WATERCUP
                            description: 完整设备编码。
                          new_version:
                            type: string
                            example: 1.0.2
                            description: 本次确认的目标固件版本。
                          confirmed:
                            type: boolean
                            example: true
                            description: 用户升级确认是否已保存。
                          notification_status:
                            type: string
                            example: sent
                            description: sent：指令已提交；failed：通知失败，确认仍有效；throttled：近期已尝试通知。
                          notification_message:
                            type: string
                            example: 升级指令已提交，不代表设备已接收或升级完成
                            description: 通知状态说明，不作为升级完成凭据。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        mac: DEMO000001-DEMO-B001-WATERCUP
                        new_version: 1.0.2
                        confirmed: true
                        notification_status: failed
                        notification_message: 确认已保存，升级通知失败，可重试；设备主动检查时仍可升级
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          mac:
                            type: string
                            example: DEMO000001-DEMO-B001-WATERCUP
                            description: 完整设备编码。
                          new_version:
                            type: string
                            example: 1.0.2
                            description: 本次确认的目标固件版本。
                          confirmed:
                            type: boolean
                            example: true
                            description: 用户升级确认是否已保存。
                          notification_status:
                            type: string
                            example: failed
                            description: sent：指令已提交；failed：通知失败，确认仍有效；throttled：近期已尝试通知。
                          notification_message:
                            type: string
                            example: 确认已保存，升级通知失败，可重试；设备主动检查时仍可升级
                            description: 通知状态说明，不作为升级完成凭据。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：设备不存在或未绑定当前用户
                    type: object
                    example:
                      errorCode: 1
                      message: 设备不存在或未绑定当前用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备不存在或未绑定当前用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：升级版本已变化，请刷新设备信息后重试
                    type: object
                    example:
                      errorCode: 1
                      message: 升级版本已变化，请刷新设备信息后重试
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 升级版本已变化，请刷新设备信息后重试
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：当前设备没有可用的OTA固件
                    type: object
                    example:
                      errorCode: 1
                      message: 当前设备没有可用的OTA固件
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 当前设备没有可用的OTA固件
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：当前设备已是该版本或更高版本，无需升级
                    type: object
                    example:
                      errorCode: 1
                      message: 当前设备已是该版本或更高版本，无需升级
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 当前设备已是该版本或更高版本，无需升级
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '08 设备事件'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                mac:
                  type: string
                  description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
                  example: DEMO000001-DEMO-B001-WATERCUP
                new_version:
                  type: string
                  description: '设备列表返回的 new_version，最长32字符；版本变化时刷新列表后重新确认。'
                  example: 1.0.2
              required:
                - account
                - mac
                - new_version
  /openapi/device/switch-prologue:
    post:
      summary: 设置设备开场白开关
      operationId: post_openapi_device_switch_prologue
      description: '修改设备缓存中的开场白开关，mac_code 使用完整编码。建议明确传整数 0/1；当前 numeric|between 校验也会接受区间内小数，最终转整数保存。与当前开关相同返回失败而非幂等成功；锁冲突提示重试。此接口是开放平台接口，errorCode 使用 0/1。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        switch_prologue: 1
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          switch_prologue:
                            type: integer
                            example: 1
                            description: '开场白开关：0 关闭、1 开启；缓存缺失默认 0。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：开关值没有改变
                    type: object
                    example:
                      errorCode: 1
                      message: 开关值没有改变
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 开关值没有改变
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：找不到mac信息
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到mac信息
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到mac信息
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：系统繁忙，请稍后再试
                    type: object
                    example:
                      errorCode: 1
                      message: 系统繁忙，请稍后再试
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 系统繁忙，请稍后再试
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '08 设备事件'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mac_code:
                  type: string
                  description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
                  example: DEMO000001-DEMO-B001-WATERCUP
                switch_prologue:
                  type: integer
                  description: '开场白开关，0 关闭、1 开启。'
                  example: 1
                  enum:
                    - 0
                    - 1
              required:
                - mac_code
                - switch_prologue
  /openapi/push/event:
    post:
      summary: 上报设备事件
      operationId: post_openapi_push_event
      description: '保存设备事件到异常上报表；mac 必须字符串。json 为事件内容，当前未做 JSON 格式验证，建议传 JSON 字符串以便存储。只记录事件，不代表下发给设备或触发业务处理。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：mac不能为空
                    type: object
                    example:
                      errorCode: 1
                      message: mac不能为空
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: mac不能为空
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '08 设备事件'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
                  example: DEMO000001-DEMO-B001-WATERCUP
                json:
                  type: string
                  description: '事件内容，建议 JSON 编码字符串；不是嵌套对象。'
                  example: '{"event":"demo","message":"测试事件"}'
              required:
                - mac
  /openapi/device/code/bind:
    post:
      summary: 通过配对码绑定设备
      operationId: post_openapi_device_code_bind
      description: '使用设备已生成的配对码为 account 绑定设备。code 从既有设备配对流程取得，本接口不生成配对码；失效或查不到返回业务失败。成功返回本次配对设备的 mac_id（数据库设备 ID）、mac_code（完整设备编码）及 bind_time（当前绑定关系开始时间，北京时间 Y-m-d H:i:s）。同一用户重复绑定保留绑定时间；解绑后重绑或换用户时重新计时。bind_time 可作为 chat/list 的 chat_created_at_start，结合 account 和 mac_code 过滤此前记录。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        mac_id: 1
                        mac_code: DEMO000001-DEMO-B001-WATERCUP
                        bind_time: '2026-10-20 10:00:00'
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          mac_id:
                            type: integer
                            example: 1
                            description: '数据库设备 ID。'
                          mac_code:
                            type: string
                            example: DEMO000001-DEMO-B001-WATERCUP
                            description: 完整设备编码。
                          bind_time:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: '当前用户与设备绑定关系的开始时间，北京时间 Y-m-d H:i:s；同用户重复绑定保留，解绑后重绑或换用户重新计时。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：code不能为空
                    type: object
                    example:
                      errorCode: 1
                      message: code不能为空
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: code不能为空
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '08 设备事件'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                code:
                  type: string
                  description: 设备配对码，按字符串传入保留前导零。
                  example: '000000'
              required:
                - account
                - code
  /openapi/device/query/touch_nums:
    get:
      summary: 查询设备触摸次数
      operationId: get_openapi_device_query_touch_nums
      description: '按 mac_code 和日期查询触摸次数。日期为空默认今天，不得晚于今天。当天读取实时缓存，历史日期读取持久化日统计；无记录返回 nums=0。按服务器日期边界判断今天。'
      parameters:
        -
          in: query
          name: mac_code
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: query
          name: date
          description: Y-m-d，默认今天，不得为未来日期。
          example: '2026-10-20'
          required: false
          schema:
            type: string
            description: Y-m-d，默认今天，不得为未来日期。
            example: '2026-10-20'
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        mac_code: DEMO000001-DEMO-B001-WATERCUP
                        date: '2026-10-20'
                        nums: 12
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          mac_code:
                            type: string
                            example: DEMO000001-DEMO-B001-WATERCUP
                            description: 完整设备编码。
                          date:
                            type: string
                            example: '2026-10-20'
                            description: 统计日期，Y-m-d。
                          nums:
                            type: integer
                            example: 12
                            description: '当日触摸次数，无记录为 0。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：日期不能大于今天
                    type: object
                    example:
                      errorCode: 1
                      message: 日期不能大于今天
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 日期不能大于今天
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：mac_code不能为空
                    type: object
                    example:
                      errorCode: 1
                      message: mac_code不能为空
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: mac_code不能为空
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '08 设备事件'
  /openapi/clone/my-timbre:
    post:
      summary: 创建克隆音色
      operationId: post_openapi_clone_my_timbre
      description: '使用 account 名下已支付、未退款且有可用名额的 pay_id 创建克隆音色。multipart/form-data 上传 audio。服务端预占名额、上传录音并分配上游音色，成功后消耗一个名额、提交延迟训练任务。成功状态 Training 不代表训练完成；通常至少等待约 305 秒后查询审核结果。当前成功 data 不含 timbre_id，需通过克隆列表获取 id。重复调用可能消耗其他剩余名额，不能自动重放不确定结果。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 已创建并提交训练，不代表审核完成
                    type: object
                    example:
                      data:
                        timbre_code: demo_voice
                        timbre_name: 示例音色
                        timbre_created_at: '2026-10-20 10:00:00'
                        timbre_platform: volcengine
                        timbre_avatar: ''
                        timbre_audio: ''
                        timbre_user_id: 123
                        timbre_expire_at: 1824000000
                        timbre_user_upload_audio: 'https://example.com/demo.wav'
                        timbre_error_msg: ''
                        timbre_state: Training
                        timbre_remaining_nums: 2
                        timbre_order_id: 456
                      total: 0
                      message: 音色训练中
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_name:
                            type: string
                            example: 示例音色
                            description: 音色名称。
                          timbre_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 音色创建日期时间。
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          timbre_avatar:
                            type: string
                            example: ''
                            description: 音色头像地址，可为空。
                          timbre_audio:
                            type: string
                            example: ''
                            description: 试听音频地址，可为空。
                          timbre_user_id:
                            type: integer
                            example: 123
                            description: '音色所属平台用户 ID；0 表示公共音色。'
                          timbre_expire_at:
                            type: integer
                            example: 1824000000
                            description: '克隆音色过期 Unix 时间戳（秒）；公共音色可为 0。'
                          timbre_user_upload_audio:
                            type: string
                            example: 'https://example.com/demo.wav'
                            description: 用户上传的训练音频地址。
                          timbre_error_msg:
                            type: string
                            example: ''
                            description: 训练/审核说明；非空时需检查业务状态。
                          timbre_state:
                            type: string
                            example: Training
                            description: '训练状态，例如 Training、Success、Failed、Active、Unknown，以上游结果为准。'
                          timbre_remaining_nums:
                            type: integer
                            example: 2
                            description: 剩余重新录音次数；是否扣减以具体流程为准。
                          timbre_order_id:
                            type: integer
                            example: 456
                            description: '关联克隆名额订单 ID。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 音色训练中
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：订单未支付或已退款
                    type: object
                    example:
                      errorCode: 1
                      message: 订单未支付或已退款
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 订单未支付或已退款
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：订单正在退款或已退款，不能创建音色
                    type: object
                    example:
                      errorCode: 1
                      message: 订单正在退款或已退款，不能创建音色
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 订单正在退款或已退款，不能创建音色
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：没有可使用的克隆名额
                    type: object
                    example:
                      errorCode: 1
                      message: 没有可使用的克隆名额
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 没有可使用的克隆名额
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                pay_id:
                  type: integer
                  description: '当前用户已支付的 pay 表 ID，取克隆列表 pay_id。'
                  example: 456
                audio:
                  type: string
                  format: binary
                  description: '录音文件，支持 MP3/WAV/M4A/AAC/OGG；受服务器上传大小配置限制。'
              required:
                - account
                - pay_id
                - audio
  /openapi/clone/my-timbre/list:
    get:
      summary: 获取我的克隆音色
      operationId: get_openapi_clone_my_timbre_list
      description: '返回 account 用户已付款的克隆订单及关联音色，不分页。未使用名额可能没有关联音色，此时 id/name/state 等字段为 null；pay_id 用于创建音色，id 为创建后音色 ID。expire_time 来自 timbre_expire_at（Unix 秒），create_time 为日期时间。is_use=0 未用、1 已用。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        -
                          id: 100
                          pay_id: 456
                          is_use: 1
                          month: 12
                          title: 示例克隆年卡
                          timbre_code: demo_voice
                          user_id: 123
                          name: 示例用户的音色
                          create_time: '2026-10-20 10:00:00'
                          expire_time: 1824000000
                          effective_month: 12
                          avatar: ''
                          user_upload_audio: 'https://example.com/demo.wav'
                          demo_audio: ''
                          error_msg: ''
                          state: Training
                          remaining_nums: 2
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: array
                        example:
                          -
                            id: 100
                            pay_id: 456
                            is_use: 1
                            month: 12
                            title: 示例克隆年卡
                            timbre_code: demo_voice
                            user_id: 123
                            name: 示例用户的音色
                            create_time: '2026-10-20 10:00:00'
                            expire_time: 1824000000
                            effective_month: 12
                            avatar: ''
                            user_upload_audio: 'https://example.com/demo.wav'
                            demo_audio: ''
                            error_msg: ''
                            state: Training
                            remaining_nums: 2
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 100
                            pay_id:
                              type: integer
                              example: 456
                            is_use:
                              type: integer
                              example: 1
                            month:
                              type: integer
                              example: 12
                            title:
                              type: string
                              example: 示例克隆年卡
                            timbre_code:
                              type: string
                              example: demo_voice
                            user_id:
                              type: integer
                              example: 123
                            name:
                              type: string
                              example: 示例用户的音色
                            create_time:
                              type: string
                              example: '2026-10-20 10:00:00'
                            expire_time:
                              type: integer
                              example: 1824000000
                            effective_month:
                              type: integer
                              example: 12
                            avatar:
                              type: string
                              example: ''
                            user_upload_audio:
                              type: string
                              example: 'https://example.com/demo.wav'
                            demo_audio:
                              type: string
                              example: ''
                            error_msg:
                              type: string
                              example: ''
                            state:
                              type: string
                              example: Training
                            remaining_nums:
                              type: integer
                              example: 2
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
  /openapi/clone/my-timbre/check-status:
    get:
      summary: 查询音色审核结果
      operationId: get_openapi_clone_my_timbre_check_status
      description: '查询 account 自己的启用克隆音色，id 为 timbre_id。创建后的查询锁约 305 秒内会拒绝查询。请求会访问上游审核状态；成功返回完整音色属性，需读取 timbre_state、timbre_error_msg、timbre_audio，而不能只看 code=200。常见状态 Training 训练中、Success 成功、Failed 失败、Active 已激活、Unknown 未知，最终以上游结果为准。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: query
          name: id
          description: '当前用户克隆音色的 timbre_id，不是 pay_id。'
          example: 100
          required: true
          schema:
            type: integer
            description: '当前用户克隆音色的 timbre_id，不是 pay_id。'
            example: 100
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        timbre_id: 100
                        timbre_code: demo_voice
                        timbre_name: 示例音色
                        timbre_gender: 1
                        timbre_age_group: 3
                        timbre_status: 1
                        timbre_tag: 自然
                        timbre_created_at: '2026-10-20 10:00:00'
                        timbre_free: 1
                        timbre_platform: volcengine
                        timbre_avatar: ''
                        timbre_audio: 'https://example.com/demo.mp3'
                        timbre_sort: 1
                        timbre_recommended: 2
                        timbre_type: 1
                        timbre_user_id: 123
                        timbre_expire_at: 1824000000
                        timbre_user_upload_audio: 'https://example.com/demo.wav'
                        timbre_error_msg: ''
                        timbre_state: Success
                        timbre_remaining_nums: 2
                        timbre_order_id: 456
                        language: zh-CN
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          timbre_id:
                            type: integer
                            example: 100
                            description: '音色 ID。'
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_name:
                            type: string
                            example: 示例音色
                            description: 音色名称。
                          timbre_gender:
                            type: integer
                            example: 1
                            description: '1 男、2 女。'
                          timbre_age_group:
                            type: integer
                            example: 3
                            description: '1 童年、2 青年、3 成年、4 中年、5 老年。'
                          timbre_status:
                            type: integer
                            example: 1
                            description: '1 启用、2 禁用。'
                          timbre_tag:
                            type: string
                            example: 自然
                            description: 音色标签。
                          timbre_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 音色创建日期时间。
                          timbre_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费；是否可使用仍需结合权益和批次权限。'
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          timbre_avatar:
                            type: string
                            example: ''
                            description: 音色头像地址，可为空。
                          timbre_audio:
                            type: string
                            example: 'https://example.com/demo.mp3'
                            description: 试听音频地址，可为空。
                          timbre_sort:
                            type: integer
                            example: 1
                            description: 音色排序值，越大越靠前。
                          timbre_recommended:
                            type: integer
                            example: 2
                            description: '1 推荐、2 非推荐。'
                          timbre_type:
                            type: integer
                            example: 1
                            description: '音色类型：1 拟人、2 情感、9 普通。'
                          timbre_user_id:
                            type: integer
                            example: 123
                            description: '音色所属平台用户 ID；0 表示公共音色。'
                          timbre_expire_at:
                            type: integer
                            example: 1824000000
                            description: '克隆音色过期 Unix 时间戳（秒）；公共音色可为 0。'
                          timbre_user_upload_audio:
                            type: string
                            example: 'https://example.com/demo.wav'
                            description: 用户上传的训练音频地址。
                          timbre_error_msg:
                            type: string
                            example: ''
                            description: 训练/审核说明；非空时需检查业务状态。
                          timbre_state:
                            type: string
                            example: Success
                            description: '训练状态，例如 Training、Success、Failed、Active、Unknown，以上游结果为准。'
                          timbre_remaining_nums:
                            type: integer
                            example: 2
                            description: 剩余重新录音次数；是否扣减以具体流程为准。
                          timbre_order_id:
                            type: integer
                            example: 456
                            description: '关联克隆名额订单 ID。'
                          language:
                            type: string
                            example: zh-CN
                            description: '语言代码，例如 zh-CN。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：音色需要训练5分钟哦~客官请稍后再来
                    type: object
                    example:
                      errorCode: 1
                      message: 音色需要训练5分钟哦~客官请稍后再来
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 音色需要训练5分钟哦~客官请稍后再来
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
  /openapi/clone/my-timbre/re-audit:
    post:
      summary: 重新提交音色录音
      operationId: post_openapi_clone_my_timbre_re_audit
      description: '重新提交自己的克隆音色录音，要求未过期、剩余次数≥1、当前非 Training、无查询锁。multipart/form-data。上游当场拒绝时仍可能 errorCode=0，但 data.timbre_state=Unknown 并有 timbre_error_msg；提交受理分支使用 code=200 返回 Training。两个成功包装历史上不同，请同时判断状态和错误信息。当前成功分支没有扣减 timbre_remaining_nums，不能假设每次重审一定减一。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      data:
                        timbre_id: 100
                        timbre_code: demo_voice
                        timbre_name: 示例音色
                        timbre_gender: 1
                        timbre_age_group: 3
                        timbre_status: 1
                        timbre_tag: 自然
                        timbre_created_at: '2026-10-20 10:00:00'
                        timbre_free: 1
                        timbre_platform: volcengine
                        timbre_avatar: ''
                        timbre_audio: ''
                        timbre_sort: 1
                        timbre_recommended: 2
                        timbre_type: 1
                        timbre_user_id: 123
                        timbre_expire_at: 1824000000
                        timbre_user_upload_audio: 'https://example.com/demo.wav'
                        timbre_error_msg: ''
                        timbre_state: Training
                        timbre_remaining_nums: 2
                        timbre_order_id: 456
                        language: zh-CN
                      total: 0
                      message: 成功
                      code: 200
                    properties:
                      data:
                        type: object
                        properties:
                          timbre_id:
                            type: integer
                            example: 100
                            description: '音色 ID。'
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_name:
                            type: string
                            example: 示例音色
                            description: 音色名称。
                          timbre_gender:
                            type: integer
                            example: 1
                            description: '1 男、2 女。'
                          timbre_age_group:
                            type: integer
                            example: 3
                            description: '1 童年、2 青年、3 成年、4 中年、5 老年。'
                          timbre_status:
                            type: integer
                            example: 1
                            description: '1 启用、2 禁用。'
                          timbre_tag:
                            type: string
                            example: 自然
                            description: 音色标签。
                          timbre_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 音色创建日期时间。
                          timbre_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费；是否可使用仍需结合权益和批次权限。'
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          timbre_avatar:
                            type: string
                            example: ''
                            description: 音色头像地址，可为空。
                          timbre_audio:
                            type: string
                            example: ''
                            description: 试听音频地址，可为空。
                          timbre_sort:
                            type: integer
                            example: 1
                            description: 音色排序值，越大越靠前。
                          timbre_recommended:
                            type: integer
                            example: 2
                            description: '1 推荐、2 非推荐。'
                          timbre_type:
                            type: integer
                            example: 1
                            description: '音色类型：1 拟人、2 情感、9 普通。'
                          timbre_user_id:
                            type: integer
                            example: 123
                            description: '音色所属平台用户 ID；0 表示公共音色。'
                          timbre_expire_at:
                            type: integer
                            example: 1824000000
                            description: '克隆音色过期 Unix 时间戳（秒）；公共音色可为 0。'
                          timbre_user_upload_audio:
                            type: string
                            example: 'https://example.com/demo.wav'
                            description: 用户上传的训练音频地址。
                          timbre_error_msg:
                            type: string
                            example: ''
                            description: 训练/审核说明；非空时需检查业务状态。
                          timbre_state:
                            type: string
                            example: Training
                            description: '训练状态，例如 Training、Success、Failed、Active、Unknown，以上游结果为准。'
                          timbre_remaining_nums:
                            type: integer
                            example: 2
                            description: 剩余重新录音次数；是否扣减以具体流程为准。
                          timbre_order_id:
                            type: integer
                            example: 456
                            description: '关联克隆名额订单 ID。'
                          language:
                            type: string
                            example: zh-CN
                            description: '语言代码，例如 zh-CN。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                      total:
                        type: integer
                        example: 0
                        description: '记录总数；非列表 successData 包装默认 0。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        timbre_id: 100
                        timbre_code: demo_voice
                        timbre_name: 示例音色
                        timbre_gender: 1
                        timbre_age_group: 3
                        timbre_status: 1
                        timbre_tag: 自然
                        timbre_created_at: '2026-10-20 10:00:00'
                        timbre_free: 1
                        timbre_platform: volcengine
                        timbre_avatar: ''
                        timbre_audio: ''
                        timbre_sort: 1
                        timbre_recommended: 2
                        timbre_type: 1
                        timbre_user_id: 123
                        timbre_expire_at: 1824000000
                        timbre_user_upload_audio: 'https://example.com/demo.wav'
                        timbre_error_msg: 请重新录制清晰录音后提交。
                        timbre_state: Unknown
                        timbre_remaining_nums: 2
                        timbre_order_id: 456
                        language: zh-CN
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          timbre_id:
                            type: integer
                            example: 100
                            description: '音色 ID。'
                          timbre_code:
                            type: string
                            example: demo_voice
                            description: 提供商音色标识。
                          timbre_name:
                            type: string
                            example: 示例音色
                            description: 音色名称。
                          timbre_gender:
                            type: integer
                            example: 1
                            description: '1 男、2 女。'
                          timbre_age_group:
                            type: integer
                            example: 3
                            description: '1 童年、2 青年、3 成年、4 中年、5 老年。'
                          timbre_status:
                            type: integer
                            example: 1
                            description: '1 启用、2 禁用。'
                          timbre_tag:
                            type: string
                            example: 自然
                            description: 音色标签。
                          timbre_created_at:
                            type: string
                            example: '2026-10-20 10:00:00'
                            description: 音色创建日期时间。
                          timbre_free:
                            type: integer
                            example: 1
                            description: '1 免费、2 收费；是否可使用仍需结合权益和批次权限。'
                          timbre_platform:
                            type: string
                            example: volcengine
                            description: 音色提供平台。
                          timbre_avatar:
                            type: string
                            example: ''
                            description: 音色头像地址，可为空。
                          timbre_audio:
                            type: string
                            example: ''
                            description: 试听音频地址，可为空。
                          timbre_sort:
                            type: integer
                            example: 1
                            description: 音色排序值，越大越靠前。
                          timbre_recommended:
                            type: integer
                            example: 2
                            description: '1 推荐、2 非推荐。'
                          timbre_type:
                            type: integer
                            example: 1
                            description: '音色类型：1 拟人、2 情感、9 普通。'
                          timbre_user_id:
                            type: integer
                            example: 123
                            description: '音色所属平台用户 ID；0 表示公共音色。'
                          timbre_expire_at:
                            type: integer
                            example: 1824000000
                            description: '克隆音色过期 Unix 时间戳（秒）；公共音色可为 0。'
                          timbre_user_upload_audio:
                            type: string
                            example: 'https://example.com/demo.wav'
                            description: 用户上传的训练音频地址。
                          timbre_error_msg:
                            type: string
                            example: 请重新录制清晰录音后提交。
                            description: 训练/审核说明；非空时需检查业务状态。
                          timbre_state:
                            type: string
                            example: Unknown
                            description: '训练状态，例如 Training、Success、Failed、Active、Unknown，以上游结果为准。'
                          timbre_remaining_nums:
                            type: integer
                            example: 2
                            description: 剩余重新录音次数；是否扣减以具体流程为准。
                          timbre_order_id:
                            type: integer
                            example: 456
                            description: '关联克隆名额订单 ID。'
                          language:
                            type: string
                            example: zh-CN
                            description: '语言代码，例如 zh-CN。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                id:
                  type: integer
                  description: '当前用户克隆音色的 timbre_id，不是 pay_id。'
                  example: 100
                audio:
                  type: string
                  format: binary
                  description: '录音文件，支持 MP3/WAV/M4A/AAC/OGG；受服务器上传大小配置限制。'
              required:
                - account
                - id
                - audio
  /openapi/clone/my-timbre/edit:
    post:
      summary: 编辑克隆音色资料
      operationId: post_openapi_clone_my_timbre_edit
      description: '编辑当前用户启用克隆音色的名称，可同时上传头像。头像使用 multipart/form-data，格式白名单 JPG/JPEG/PNG/GIF/SVG，受图像压缩能力限制。不传 avatar 保留原头像；成功不返回详情，可重新查询列表。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      message: 成功
                      code: 200
                    properties:
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      code:
                        type: integer
                        example: 200
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                id:
                  type: integer
                  description: '当前用户克隆音色的 timbre_id，不是 pay_id。'
                  example: 100
                name:
                  type: string
                  description: 新音色名称，必填；该方法未额外设置长度校验，仍受数据库限制。
                  example: 我的示例音色
                avatar:
                  type: string
                  format: binary
                  description: 可选头像文件。
              required:
                - account
                - id
                - name
  /openapi/clone/my-timbre/pay/list:
    get:
      summary: 获取克隆音色支付列表
      operationId: get_openapi_clone_my_timbre_pay_list
      description: '获取 account 用户地区对应的启用克隆商品，不分页。语言当前固定 zh-CN，不受 Accept-Language 切换。地区为国外时 addr_type=2，否则为国内；ios_price 国内按配置费率计算，国外等于 price。返回商品 id 对应 corporation_buy 的 goods_id。'
      parameters:
        -
          in: query
          name: account
          description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
          example: partner_demo_001
          required: true
          schema:
            type: string
            description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
            example: partner_demo_001
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        -
                          id: 1
                          title: 示例克隆年卡
                          show_price: '99.00'
                          price: '99.00'
                          status: 1
                          month: 12
                          quantity: 1
                          create_at: '2026-10-20 10:00:00'
                          update_at: '2026-10-20 10:00:00'
                          unique_value: demo_clone_year
                          language: zh-CN
                          addr_type: 1
                          ios_price: 99
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example:
                          -
                            id: 1
                            title: 示例克隆年卡
                            show_price: '99.00'
                            price: '99.00'
                            status: 1
                            month: 12
                            quantity: 1
                            create_at: '2026-10-20 10:00:00'
                            update_at: '2026-10-20 10:00:00'
                            unique_value: demo_clone_year
                            language: zh-CN
                            addr_type: 1
                            ios_price: 99
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: 示例克隆年卡
                            show_price:
                              type: string
                              example: '99.00'
                            price:
                              type: string
                              example: '99.00'
                            status:
                              type: integer
                              example: 1
                            month:
                              type: integer
                              example: 12
                            quantity:
                              type: integer
                              example: 1
                            create_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            update_at:
                              type: string
                              example: '2026-10-20 10:00:00'
                            unique_value:
                              type: string
                              example: demo_clone_year
                            language:
                              type: string
                              example: zh-CN
                            addr_type:
                              type: integer
                              example: 1
                            ios_price:
                              type: integer
                              example: 99
                  -
                    description: 业务失败：找不到用户
                    type: object
                    example:
                      errorCode: 1
                      message: 找不到用户
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 找不到用户
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
  /openapi/clone/my-timbre/pay/corporation_buy:
    post:
      summary: 公司预支付克隆音色
      operationId: post_openapi_clone_my_timbre_pay_corporation_buy
      description: '使用接入方公司余额购买克隆商品并给用户发放名额。goods_id 来源克隆商品列表。当前余额预检使用入参 amount，但实际扣款使用服务端商品 price；调用方应传商品价格，不能将较小 amount 视为折扣。会真实扣款、生成支付和克隆订单，无请求幂等键，重复调用可能重复扣款。成功不返回 pay_id，随后查询克隆列表获取。'
      parameters:
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data: []
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: array
                        example: []
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：公司不存在！
                    type: object
                    example:
                      errorCode: 1
                      message: 公司不存在！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 公司不存在！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：公司不可用！
                    type: object
                    example:
                      errorCode: 1
                      message: 公司不可用！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 公司不可用！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：公司余额不足！
                    type: object
                    example:
                      errorCode: 1
                      message: 公司余额不足！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 公司余额不足！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: 业务失败：账号不存在！
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                  -
                    description: '账号不存在或无权访问（HTTP 200）'
                    type: object
                    example:
                      errorCode: 1
                      message: 账号不存在或不属于当前接入方！
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 账号不存在或不属于当前接入方！
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
      tags:
        - '09 音色克隆'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  type: string
                  description: '接入方注册的用户账号；最长 64 字符。鉴权后校验当前公司的账号绑定，历史用户仅兼容当前公司配置的 appid。账号不存在或无权访问时失败，通过后映射为平台主账号。'
                  example: partner_demo_001
                goods_id:
                  type: integer
                  description: '克隆商品配置 ID。'
                  example: 1
                amount:
                  type: number
                  description: '预检金额（元），请与商品 price 一致；实际扣款由服务端商品价决定。'
                  example: 99
              required:
                - account
                - goods_id
                - amount
  /openapi/content/classif/list:
    get:
      summary: 获取内容分类
      operationId: get_openapi_content_classif_list
      description: '按 Accept-Language（默认 zh-CN）返回启用的内容分类，module=1。mac_code 必填；已绑定用户按关联设备栏目权限筛选。功能未开启时成功返回 lists=[]、manualInfo=null。普通查询按 sort 降序；manualInfo 按标题含“百科”取第一条，可能为空，不额外按语言筛选。'
      parameters:
        -
          in: query
          name: mac_code
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: query
          name: device_type
          description: 可选设备类型，按分类配置值精确筛选。
          example: null
          required: false
          schema:
            type: integer
            description: 可选设备类型，按分类配置值精确筛选。
            example: null
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        lists:
                          -
                            id: 1
                            name: 示例百科
                            pid: 0
                            status: 1
                            module: 1
                            sort: 1
                            language: zh-CN
                            device_type: 1
                            instruction: 百科
                            select_show_name: 示例百科
                        manualInfo:
                          id: 1
                          title: 百科手册
                          content: 示例使用说明
                          sort: 1
                          create_at: '2026-10-20 10:00:00'
                          language: zh-CN
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          lists:
                            type: array
                            example:
                              -
                                id: 1
                                name: 示例百科
                                pid: 0
                                status: 1
                                module: 1
                                sort: 1
                                language: zh-CN
                                device_type: 1
                                instruction: 百科
                                select_show_name: 示例百科
                            description: '启用的内容分类数组，透传 ContentClassify 模型属性。'
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                name:
                                  type: string
                                  example: 示例百科
                                pid:
                                  type: integer
                                  example: 0
                                status:
                                  type: integer
                                  example: 1
                                module:
                                  type: integer
                                  example: 1
                                sort:
                                  type: integer
                                  example: 1
                                language:
                                  type: string
                                  example: zh-CN
                                device_type:
                                  type: integer
                                  example: 1
                                instruction:
                                  type: string
                                  example: 百科
                                select_show_name:
                                  type: string
                                  example: 示例百科
                          manualInfo:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                                description: '记录 ID，具体对应实体见接口说明。'
                              title:
                                type: string
                                example: 百科手册
                                description: 标题或商品名称。
                              content:
                                type: string
                                example: 示例使用说明
                                description: '手册正文；SSE 中为增量文本。'
                              sort:
                                type: integer
                                example: 1
                                description: 排序值。
                              create_at:
                                type: string
                                example: '2026-10-20 10:00:00'
                                description: 创建日期时间。
                              language:
                                type: string
                                example: zh-CN
                                description: '语言代码，例如 zh-CN。'
                            description: '按标题包含“百科”查得的第一条手册原始模型，可能为 null。'
                            nullable: true
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        lists: []
                        manualInfo: null
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          lists:
                            type: array
                            example: []
                            description: '启用的内容分类数组，透传 ContentClassify 模型属性。'
                          manualInfo:
                            type: string
                            example: null
                            description: '按标题包含“百科”查得的第一条手册原始模型，可能为 null。'
                            nullable: true
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：设备码不能为空
                    type: object
                    example:
                      errorCode: 1
                      message: 设备码不能为空
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备码不能为空
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '10 内容资源'
  /openapi/content/list:
    get:
      summary: 获取内容列表
      operationId: get_openapi_content_list
      description: '按分类、关键字和 Accept-Language 获取启用内容。设备无用户缓存时只取默认内容；已绑定用户按栏目授权筛选。功能关闭时返回标准空分页。分页参数 page/perPage；data.data 为列表，data.total 为总数。未绑定分支列表还带 author，已绑定分支仅 id/title，调用方不能假设都有 author。'
      parameters:
        -
          in: query
          name: mac_code
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: query
          name: class_id
          description: '内容分类 ID，必填。'
          example: 1
          required: true
          schema:
            type: integer
            description: '内容分类 ID，必填。'
            example: 1
        -
          in: query
          name: keyword
          description: 标题模糊搜索。
          example: null
          required: false
          schema:
            type: string
            description: 标题模糊搜索。
            example: null
        -
          in: query
          name: page
          description: '页码，默认 1。'
          example: 1
          required: false
          schema:
            type: integer
            description: '页码，默认 1。'
            example: 1
        -
          in: query
          name: perPage
          description: '每页数量，默认 20。'
          example: 20
          required: false
          schema:
            type: integer
            description: '每页数量，默认 20。'
            example: 20
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        current_page: 1
                        data:
                          -
                            id: 1
                            title: 示例内容
                            author: 示例作者
                        first_page_url: 'http://localhost:8000/?page=1'
                        from: 1
                        last_page: 1
                        last_page_url: 'http://localhost:8000/?page=1'
                        links:
                          -
                            url: null
                            label: 上一页
                            active: false
                          -
                            url: 'http://localhost:8000/?page=1'
                            label: '1'
                            active: true
                        next_page_url: null
                        path: 'http://localhost:8000/'
                        per_page: 20
                        prev_page_url: null
                        to: 1
                        total: 1
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          current_page:
                            type: integer
                            example: 1
                            description: 当前页码。
                          data:
                            type: array
                            example:
                              -
                                id: 1
                                title: 示例内容
                                author: 示例作者
                            description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                title:
                                  type: string
                                  example: 示例内容
                                author:
                                  type: string
                                  example: 示例作者
                          first_page_url:
                            type: string
                            example: 'http://localhost:8000/?page=1'
                            description: 第一页链接；示例地址仅演示结构。
                          from:
                            type: integer
                            example: 1
                            description: '当前页起始序号；空页可为 null。'
                          last_page:
                            type: integer
                            example: 1
                            description: 最后一页页码。
                          last_page_url:
                            type: string
                            example: 'http://localhost:8000/?page=1'
                            description: 最后一页链接。
                          links:
                            type: array
                            example:
                              -
                                url: null
                                label: 上一页
                                active: false
                              -
                                url: 'http://localhost:8000/?page=1'
                                label: '1'
                                active: true
                            description: 分页链接数组。
                            items:
                              type: object
                              properties:
                                url:
                                  type: string
                                  example: null
                                  nullable: true
                                label:
                                  type: string
                                  example: 上一页
                                active:
                                  type: boolean
                                  example: false
                          next_page_url:
                            type: string
                            example: null
                            description: '下一页链接，无下一页时为 null。'
                            nullable: true
                          path:
                            type: string
                            example: 'http://localhost:8000/'
                            description: 分页接口基础地址。
                          per_page:
                            type: integer
                            example: 20
                            description: 每页条数。
                          prev_page_url:
                            type: string
                            example: null
                            description: '上一页链接，无上一页时为 null。'
                            nullable: true
                          to:
                            type: integer
                            example: 1
                            description: '当前页结束序号；空页可为 null。'
                          total:
                            type: integer
                            example: 1
                            description: '记录总数；非列表 successData 包装默认 0。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：设备码不能为空
                    type: object
                    example:
                      errorCode: 1
                      message: 设备码不能为空
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备码不能为空
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '10 内容资源'
  /openapi/content/classif/child/list:
    get:
      summary: 获取内容子分类
      operationId: get_openapi_content_classif_child_list
      description: '按父分类 pid 返回直属子分类，不递归。pid 默认 0；语言、设备类型、启用状态与设备栏目权限规则同分类列表。功能未开启时返回空列表和 null 手册。'
      parameters:
        -
          in: query
          name: mac_code
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: query
          name: pid
          description: '父分类 ID，默认 0 为根层级。'
          example: 0
          required: false
          schema:
            type: integer
            description: '父分类 ID，默认 0 为根层级。'
            example: 0
        -
          in: query
          name: device_type
          description: 可选设备类型，按分类配置值筛选。
          example: null
          required: false
          schema:
            type: integer
            description: 可选设备类型，按分类配置值筛选。
            example: null
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        lists:
                          -
                            id: 1
                            name: 示例百科
                            pid: 0
                            status: 1
                            module: 1
                            sort: 1
                            language: zh-CN
                            device_type: 1
                            instruction: 百科
                            select_show_name: 示例百科
                        manualInfo:
                          id: 1
                          title: 百科手册
                          content: 示例使用说明
                          sort: 1
                          create_at: '2026-10-20 10:00:00'
                          language: zh-CN
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          lists:
                            type: array
                            example:
                              -
                                id: 1
                                name: 示例百科
                                pid: 0
                                status: 1
                                module: 1
                                sort: 1
                                language: zh-CN
                                device_type: 1
                                instruction: 百科
                                select_show_name: 示例百科
                            description: '启用的内容分类数组，透传 ContentClassify 模型属性。'
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  example: 1
                                name:
                                  type: string
                                  example: 示例百科
                                pid:
                                  type: integer
                                  example: 0
                                status:
                                  type: integer
                                  example: 1
                                module:
                                  type: integer
                                  example: 1
                                sort:
                                  type: integer
                                  example: 1
                                language:
                                  type: string
                                  example: zh-CN
                                device_type:
                                  type: integer
                                  example: 1
                                instruction:
                                  type: string
                                  example: 百科
                                select_show_name:
                                  type: string
                                  example: 示例百科
                          manualInfo:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                                description: '记录 ID，具体对应实体见接口说明。'
                              title:
                                type: string
                                example: 百科手册
                                description: 标题或商品名称。
                              content:
                                type: string
                                example: 示例使用说明
                                description: '手册正文；SSE 中为增量文本。'
                              sort:
                                type: integer
                                example: 1
                                description: 排序值。
                              create_at:
                                type: string
                                example: '2026-10-20 10:00:00'
                                description: 创建日期时间。
                              language:
                                type: string
                                example: zh-CN
                                description: '语言代码，例如 zh-CN。'
                            description: '按标题包含“百科”查得的第一条手册原始模型，可能为 null。'
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：设备码不能为空
                    type: object
                    example:
                      errorCode: 1
                      message: 设备码不能为空
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 设备码不能为空
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '10 内容资源'
  /openapi/content/details:
    get:
      summary: 获取内容详情
      operationId: get_openapi_content_details
      description: '返回内容详情，设备未绑定用户时仅可读默认内容，已绑定时按栏目授权筛选；查不到返回业务失败。背景图片和音乐地址统一按存储规则转换。translation 是存储的翻译字段，可能为空；此入口未按 Accept-Language 额外过滤内容 ID。'
      parameters:
        -
          in: query
          name: id
          description: '内容 ID，取 content/list 返回值。'
          example: 1
          required: true
          schema:
            type: integer
            description: '内容 ID，取 content/list 返回值。'
            example: 1
        -
          in: query
          name: mac_code
          description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
          example: DEMO000001-DEMO-B001-WATERCUP
          required: true
          schema:
            type: string
            description: '完整设备编码（不是数据库 mac_id），包括公司、批次和产品后缀；最长 64 字符。'
            example: DEMO000001-DEMO-B001-WATERCUP
        -
          in: header
          name: Accept-Language
          description: '响应文案/产品名称/内容语言，默认 zh-CN；具体接口是否筛选语言见业务说明。'
          example: zh-CN
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  -
                    description: 成功（虚构数据结构示例）
                    type: object
                    example:
                      errorCode: 0
                      message: 成功
                      data:
                        id: 1
                        instruction: 示例指令
                        author: 示例作者
                        title: 示例内容
                        content_text: 示例正文
                        bg_img_128_128: ''
                        bg_img_240_240: ''
                        bg_img_240_320: ''
                        bg_img_400_240: ''
                        bg_music: ''
                        translation: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 0
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 成功
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      data:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                            description: '记录 ID，具体对应实体见接口说明。'
                          instruction:
                            type: string
                            example: 示例指令
                            description: 内容或分类指令词。
                          author:
                            type: string
                            example: 示例作者
                            description: 内容作者。
                          title:
                            type: string
                            example: 示例内容
                            description: 标题或商品名称。
                          content_text:
                            type: string
                            example: 示例正文
                            description: 内容正文。
                          bg_img_128_128:
                            type: string
                            example: ''
                            description: '128×128 背景图地址。'
                          bg_img_240_240:
                            type: string
                            example: ''
                            description: '240×240 背景图地址。'
                          bg_img_240_320:
                            type: string
                            example: ''
                            description: '240×320 背景图地址。'
                          bg_img_400_240:
                            type: string
                            example: ''
                            description: '400×240 背景图地址。'
                          bg_music:
                            type: string
                            example: ''
                            description: 背景音乐地址，可为空。
                          translation:
                            type: string
                            example: ''
                            description: 存储的翻译内容，可为空。
                        description: '业务数据；失败时可能缺失、为空数组或 null，按具体响应示例判断。'
                  -
                    description: 业务失败：内容不存在
                    type: object
                    example:
                      errorCode: 1
                      message: 内容不存在
                      errType: ''
                    properties:
                      errorCode:
                        type: integer
                        example: 1
                        description: '业务码：0 成功、1 失败；历史 code 包装以各接口示例为准。'
                      message:
                        type: string
                        example: 内容不存在
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
                      errType:
                        type: string
                        example: ''
                        description: '附加错误分类；可能是空字符串、数字或数字字符串，不是 HTTP 状态。'
                  -
                    description: '鉴权失败（HTTP 200，检查响应体）'
                    type: object
                    example:
                      code: 401
                      message: token验证失败，请重新获取
                    properties:
                      code:
                        type: integer
                        example: 401
                        description: '历史业务码，成功常为 200；需与 HTTP 状态分别判断。'
                      message:
                        type: string
                        example: token验证失败，请重新获取
                        description: '业务提示；可能随 Accept-Language 改变，不应通过提示文本判断成功。'
      tags:
        - '10 内容资源'