多语言短剧 MLS 接口文档（tool/mls）

文档更新时间：2026-07-23

线上文档基址：https://doc.guangdianyun.tv/docs/b-ym（本文以该页为基准同步至仓库；代码块使用 json 语法高亮。线上原文末尾错误的「### 17. submitMlsPay」段落已剔除。）

免登录接口的完整列表以网关 code/apaasTool/mls/index.php 中常量 NO_TOKEN_CMDS 为准；与下表「附录 B」交叉核对。

调用路径：/mls/tool/xxx 或 /mls/mlsUser/xxx（由 server 参数 tool/命令 或 mlsUser/命令 决定）。除下文附录 B所列及另有说明外，一般需传 token。本文档不包含 Tag、parentUin、userId 等由网关注入的字段说明。

请求约定：所有 POST 类型接口均使用Content-Type: application/json提交请求体（除 8.1 分片上传直传服务使用multipart/form-data外）。

密码约定（2026-03-23 更新）：所有密码字段均由前端加密后传输。后端不再对入参密码做二次加密处理；其中注册入库使用PASSWORD('...')写入数据库。

通用出参结构：

【2026-07-24 变更摘要】登录会话增加 hasPassword

• 各渠道登录 / 换票签发会话时统一写入 hasPassword（boolean）：password 非空为 true，空/NULL 为 false。
• 本变更上线前已登录的旧会话没有该字段；前端须按「字段存在且值为 false」判断未设置密码，字段缺失不要当成未设密码。
• 已登录用户通过 changePassword 首次设置密码成功后，会刷新当前 Redis 会话，补齐 hasPassword=true。

【2026-07-23 变更摘要】登录会话渠道字段 + 查渠道基础信息

• 登录态（getUserInfo / Redis 会话）明确包含 platform_code、platform_user_key（渠道用户非空）。
• 新增 getChannelPlatformInfo：按 platform_code 查渠道名称、充值跳转地址等，供前端判断是否跳转外部充值。

【2026-07-23 变更摘要】checkToken：仅 ady 为渠道用户

• sourceFrom=ady：渠道用户（写 platform_code / platform_user_key）；checkToolAccess 用 aodianyun.com；按 key 查不到则新建 uin。
• 非 ady：普通用户，只按 uin 补全必要信息，不写渠道标识。
• 渠道标识环境变量：MLS_ADY_PLATFORM_CODE（仅 ady 分支使用）。

【2026-07-21 变更摘要】checkToken 支持 sourceFrom=ady

• sourceFrom（可选，固定值 ady）：为 ady 时，checkToolAccess 请求域名使用 aodianyun.com；仅按 platform_user_key 查用户，不存在则 createMlsUserWithIpaas 重新生成 uin。
• 渠道标识改为环境变量 MLS_ADY_PLATFORM_CODE。

【2026-07-20 变更摘要】checkToken 支持 apaas 换票

• 新增文档章节 §12.0 /mls/tool/checkToken。
• subToken 以 apaas 开头时：调用控制台 checkToolAccess（subType=mls）换取用户；若 mls_user 不存在则按渠道补全 mls_user / mls_user_dms / 积分账户，并签发 MLS 登录态。
• 非 apaas 前缀：仍从 Redis 校验已有会话（与原先一致）。

【2026-07-24 变更摘要】任务类型「是否需传原片」与无源片计费时长

• mls_mode_type 新增 requires_origin（默认 1 需原片，兼容存量）。迁移脚本：sql/mls_mode_type_requires_origin.sql。
• getMlsModeTypeList 返回 requires_origin；管理后台任务类型设置可配置。
• addMlsTask：当类型 requires_origin=false 且未传 origin_url / drama_video_id 时，按 resources 顺序取第一个能解析出时长的资源 作为任务 duration（避免多文件全量查询）：字幕(srt/vtt)下载解析结束时间；音视频走媒资 getUserUploadDvr。解析失败可回退入参 duration。
• 无源片任务写入空 origin_url、origin_ready=1（无需预处理），OpenTool 可直接拉取。
• checkMlsAmount：不需原片的类型在 duration 未传或为 0 时可传 resources 按同上规则推算时长。

【2026-07-17 变更摘要】任务素材来源（前端上传 / 后端生成）

• mls_resource_file 新增 source：upload 前端上传，backend 后端生成（历史数据默认 backend）。迁移脚本：sql/mls_resource_file_source.sql。
• addMlsTask 支持可选入参 resources（数组）：创建任务时一并写入前端上传素材（language / fileType / fileUrl）。
• 新增 saveMlsTaskResource（新增/编辑素材）、deleteMlsTaskResource（软删素材）；编辑时软删原记录再插入新记录。resStatus=1 处理中不允许改素材。
• jobResource 每项额外返回 id、source。
• OpenTool saveMlsResourceFile：source 固定为 backend；同键已有记录时改为软删原记录再插入（不再原地 UPDATE）。

【2026-06-11 变更摘要】任务类型（mode_type）与非全流程

• 任务支持多种处理类型（mode_type），配置来自表 mls_mode_type，接口 getMlsModeTypeList 拉取（含单价、是否需选语种）。
• 创建任务新增入参 mode_type（默认 full_pipeline）；是否必填 languages 由类型的 requires_language 决定。
• 任务新增字段：mode_type、job_id（新任务为 32 位 hex；老数据默认 001）。priority 为保留字段，前端不可传。
• getUserMlsList / getMlsDetail 额外返回 jobResource（中间产物，结构见下文）。
• 计费（2026-07-17 更新）：所需积分 = max(时长, 30) × (base_price_per_second + lang_price_per_second × N + 时间戳校对?)；N 仅 requires_language=true 时取语种数，否则为 0。param.CONSOLE_SUBTITLE_TIMESTAMP_CHECK 为真时另加 1×计费秒（整单一次）。存储本期不计费。预占按任务剩余未扣部分计算。
• updateMlsTask：不需选语种的类型不允许修改 languages。
• retryMlsTask：每次重试生成新 job_id 并返回；不需选语种的类型仅重置任务状态；已扣前置/时间戳校对不重扣，仅对新成功语种扣叠加费。

【2026-06-17 变更摘要】任务类型索引（mode_type_index）

• mls_mode_type、mls_list 新增 mode_type_index：同一索引可对应多种 mode_type，用于前端分类 Tab / 分组列表查询。
• getMlsModeTypeList 返回 mode_type_index；addMlsTask 创建时按所选 mode_type 自动写入对应索引，无需客户端传参。
• getUserMlsList 新增入参 mode_type_index（分组查询，不传返回全部）；可与 mode_type（精确类型）组合使用。

【2026-06-30 变更摘要】任务级环境变量 param

• mls_list 新增字段 param（TEXT，默认 '{}'）：任务级环境变量 JSON 对象，供处理节点 Docker 阶段 -e KEY=VALUE 使用。
• addMlsTask、submitMlsDramaTasks、updateMlsTask 支持可选入参 param（object）；不传表示不修改（更新接口）或视为 {}（创建接口）。
• getUserMlsList、getMlsDetail 返回 param（JSON 对象，非字符串）。
• retryMlsTask 不需传 param，重试沿用创建时入库的值。
• 键名须符合环境变量规则；非法键名与系统保留键由服务端静默丢弃。完整说明见 附录 C。

【2026-07-07 变更摘要】视频预处理（转码 + 网络上传）

• 超规格源视频（分辨率 / 格式 / 帧率 / 码率任一超限）在入库或创建任务时异步预处理：转码产出 B → 网络上传 PULL → 最终源地址 C，并删除用户首次上传的 A。
• mls_list 新增 origin_ready：0 源片预处理中，1 可被 AI 处理节点拉取。OpenTool getUserMlsTaskList 仅返回 origin_ready=1 且 resStatus=0 的任务。
• mls_drama_video 新增 origin_ready、preprocess_status、preprocess_fail_msg；剧集详情 videos 列表返回上述字段。
• addMlsDramaVideo：上传后若需预处理则自动启动；addMlsTask：单条任务创建时同理。
• submitMlsDramaTasks：允许预处理未完成时先创建任务（origin_ready=0）；预处理完成后自动更新关联任务的 origin_url 并置 origin_ready=1；若某视频 preprocess_status=3（预处理失败）则整批拒绝并提示重试预处理。
• 新增 retryMlsVideoPreprocess（§6.1）：预处理失败重试；有转码产出 B 时仅重跑 PULL，否则从 A 重新转码。
• retryMlsTask（§6）：若 origin_ready=0 或关联视频预处理失败，会先自动预处理重试，再重置 AI 任务状态；响应可含 preprocess_retry。
• 预处理流水线、字段与触发规则详见 §19；底层 DVR/DMS 回调见 code/apaasTool/api/tool/底层服务接口文档.md。

1. /mls/tool/getSupportLanguageList - 获取支持语言列表

获取多语言支持的语言配置列表。返回范围由当前登录用户在mls_user_conf.config.languages决定（与getUserConf中config.languages一致）：

• basic（默认）：仅id <= 12且满足enable条件的语言。
• all：enable条件下全部语言，不再限制id。

无有效uin或库中无配置行时，按apiBase默认languages=basic处理。不再按parentUin白名单区分。

入参

出参

请求示例

{
  "token": "xxx",
  "enable": "1"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "code": "zh",
        "name": "中文",
        "enable": 1
      }
    ]
  }
}

1.1 /mls/tool/getMlsModeTypeList - 获取任务类型列表

获取 MLS 可创建的任务类型（读 mls_mode_type 表，服务端 Redis 缓存约 1 小时）。创建任务前先调此接口，用于渲染类型下拉、控制是否展示语种选择、展示单价说明。

入参

出参

当前默认类型（以库配置为准）

上表仅为示例；迁移脚本会把旧 price_per_second 按「需语种→全部记入 lang，否则记入 base」兼容拆分，产品可在后台改成文档口径（如 6+3）。

请求示例

{
  "token": "xxx"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "mode_type": "full_pipeline",
      "mode_name": "全流程",
      "mode_type_index": "full_pipeline",
      "price_per_second": 9,
      "base_price_per_second": 6,
      "lang_price_per_second": 3,
      "requires_language": true,
      "requires_origin": true,
      "remark": "多语言全流程输出：前置+语种叠加"
    },
    {
      "mode_type": "subtitle_erase_dialog",
      "mode_name": "字幕擦除-对话",
      "mode_type_index": "subtitle_erase",
      "price_per_second": 3,
      "base_price_per_second": 3,
      "lang_price_per_second": 0,
      "requires_language": false,
      "requires_origin": true,
      "remark": "不需选语种"
    }
  ]
}

2. /mls/tool/getUserMlsList - 获取多语言任务列表

分页查询当前用户的多语言输出任务列表（仅未删除）。支持按 create_time 创建时间范围、按 mode_type 精确类型、按 mode_type_index 分类分组、按 source_type 来源过滤、按 drama_video_id 所属集 ID 过滤（均可选）。

【2026-07-08 变更】三级结构：入参新增可选 drama_video_id（按集过滤）；返回每条任务额外包含 drama_video_id（所属集 ID，未关联时为 0）。

【2026-06-11 变更】每条任务额外返回 mode_type、job_id、jobResource（中间资源产物，结构同 OpenTool getMlsJobResource.data）。

【2026-06-17 变更】新增入参 mode_type、mode_type_index：不传则返回全部；mode_type 精确匹配单类型，mode_type_index 按分类索引分组查询（可返回该索引下多种 mode_type 的任务）。合法值见 getMlsModeTypeList。

【2026-06-24 变更】新增入参 source_type 来源过滤；每条任务返回 source_type：batch 批量剧集提交创建，single 单任务创建。不传或传 all 返回全部来源。

【2026-07-07 变更】每条任务额外返回 origin_ready（int）：0 源视频预处理中，AI 暂不可拉取；1 源片就绪。预处理失败时任务可能为 resStatus=4 且 origin_ready=0，需先 §6.1 retryMlsVideoPreprocess 或 §6 retryMlsTask（会自动连带预处理重试）。

入参

出参

jobResource 结构说明（仅 fileStatus=1 的成功资源）：

{
  "original": {
    "subtitle": { "id": 12, "url": "https://xxx/chat.srt", "source": "upload", "uptime": 1798732799 },
    "voice": { "id": 13, "url": "https://xxx/voice.wav", "source": "backend", "uptime": 1798732799 }
  },
  "english": {
    "subtitle": { "id": 14, "url": "https://xxx/en.srt", "source": "backend", "uptime": 1798732799 }
  }
}

• 外层 key 为语种（原文字幕等为 original）。
• 内层 key 为资源类型 fileType（如 subtitle、voice、audioRaw、asrSubtitle、cloneVoice 等）。
• 每项含 id（资源主键，编辑/删除时用）、url、source（upload 前端上传 / backend 后端生成）、uptime（秒级时间戳）。

请求示例

{
  "token": "xxx",
  "page": 1,
  "num": 15,
  "title": "短剧",
  "mode_type_index": "subtitle_erase",
  "createTimeStart": 1704067200,
  "createTimeEnd": 1704153600
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "episodeId": 1,
      "dramaId": 0,
      "drama_video_id": 0,
      "uin": 12345,
      "parentId": "01",
      "userId": 1000,
      "title": "任务标题",
      "origin_url": "http://xxx/source.mp4",
      "languages": "zh,en",
      "mode_type": "full_pipeline",
      "source_type": "single",
      "mode_type_index": "full_pipeline",
      "job_id": "e8457f8f008a241deb9934929518561d",
      "param": {},
      "origin_ready": 1,
      "duration": 0,
      "resStatus": 0,
      "results": "[{\"language\":\"zh\",\"status\":0,\"uptime\":0,\"url\":\"\"}]",
      "thumbnail": "https://1.jpg",
      "jobResource": {
        "original": {
          "subtitle": { "url": "https://xxx/chat.srt", "uptime": 1798732799 }
        }
      },
      "is_del": 0,
      "create_time": 1770447600,
      "uptime": 1770447600
    }
  ],
  "total": 10
}

非全流程且不需选语种的类型：languages 可能为空字符串，results 可能为 []，jobResource 仍可能有中间产物。

resStatus 枚举：0 待处理，1 处理中，2 部分完成，3 全部完成，4 全部失败。

与预处理的关系：resStatus=0 且 origin_ready=0 表示任务已创建但源片仍在预处理，OpenTool 不会拉取；预处理成功后服务端会将 origin_ready 置为 1 并更新 origin_url（及 duration / thumbnail 如有）。

results 单条status（与mls_list.results JSON 一致）：0 待处理，1 处理中，2 成功，3 失败，4 待审核（用户开启成片审核时，管道回调成功可先入库为待审核，见下文附录 A）。

3. /mls/tool/getMlsDetail - 获取多语言任务详情

根据任务 episodeId 查询单条任务详情。

【2026-06-11 变更】data 额外包含 mode_type、job_id、jobResource，含义与 §2 getUserMlsList 一致。

【2026-06-24 变更】data 额外包含 source_type，含义与 §2 getUserMlsList 一致。

【2026-06-30 变更】data 额外包含 param（JSON 对象，非字符串），无配置时为 {}。

【2026-07-07 变更】data 额外包含 origin_ready，含义与 §2 getUserMlsList 一致。

【2026-07-08 变更】data 额外包含 drama_video_id（所属集 ID，未关联为 0），含义与 §2 getUserMlsList 一致。

入参

出参

请求示例

{
  "token": "xxx",
  "episodeId": 1
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "episodeId": 1,
    "dramaId": 0,
    "drama_video_id": 0,
    "uin": 12345,
    "parentId": "01",
    "userId": 1000,
    "title": "任务标题",
    "origin_url": "http://xxx/source.mp4",
    "languages": "zh,en",
    "mode_type": "full_pipeline",
    "job_id": "e8457f8f008a241deb9934929518561d",
    "param": {},
    "duration": 0,
    "resStatus": 0,
    "results": "[{\"language\":\"zh\",\"status\":0,\"uptime\":0,\"url\":\"\"}]",
    "jobResource": {
      "original": {
        "subtitle": { "url": "https://xxx/chat.srt", "uptime": 1798732799 }
      }
    },
    "is_del": 0,
    "create_time": 1770447600,
    "uptime": 1770447600
  }
}

4. /mls/tool/addMlsTask - 新增多语言任务

创建一条多语言输出任务。mode_type 决定计费规则及是否必选 languages；需选语种时 results 按 languages 初始化为待处理，否则 results 为 []。

【2026-06-17 变更】服务端会根据所选 mode_type 从 mls_mode_type 读取并写入 mode_type_index，客户端无需传该字段。

【2026-06-30 变更】新增可选入参 param（object）：任务级环境变量；不传或 {} 表示无附加变量。规则见 附录 C。

【2026-07-07 变更】若源视频需预处理（见 §19），创建成功后任务 origin_ready=0，后台异步转码 + 网络上传；完成后自动置 origin_ready=1 并更新源地址。预处理启动失败返回 flag=110。

【2026-07-08 变更】三级结构：创建任务时会自动创建集（mls_drama_video）并在集层做预处理；也可传 drama_video_id 在已有集下创建任务（复用集源片，不再走任务级转码）。

【2026-07-17 变更】新增可选入参 resources：创建任务时一并写入前端上传素材，见下方说明。

【2026-07-24 变更】当任务类型 requires_origin=false 时，可不传 origin_url / drama_video_id；须传 resources（字幕或音视频）或显式 duration。服务端按 resources 顺序取第一个可解析时长的资源写入任务时长并走既有计费预占。

入参

resources[] 单项：

同一请求内 language+fileType 不可重复。

出参

请求示例（全流程）

{
  "token": "xxx",
  "title": "我的短剧任务",
  "origin_url": "http://xxx/source.mp4",
  "mode_type": "full_pipeline",
  "languages": "zh,en"
}

请求示例（带前端上传素材）

{
  "token": "xxx",
  "title": "我的短剧任务",
  "origin_url": "http://xxx/source.mp4",
  "mode_type": "full_pipeline",
  "languages": "zh,en",
  "resources": [
    { "language": "original", "fileType": "subtitle", "fileUrl": "https://xxx/chat.srt" },
    { "language": "original", "fileType": "voice", "fileUrl": "https://xxx/voice.wav" }
  ]
}

请求示例（带 param）

{
  "token": "xxx",
  "title": "我的短剧任务",
  "origin_url": "http://xxx/source.mp4",
  "mode_type": "full_pipeline",
  "languages": "zh,en",
  "param": {
    "CONSOLE_ADAPTIVE_TIME_LEN": false,
    "CONSOLE_XXX": "1"
  }
}

请求示例（非全流程，不需选语种）

{
  "token": "xxx",
  "title": "字幕擦除任务",
  "origin_url": "http://xxx/source.mp4",
  "mode_type": "subtitle_erase_dialog"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "episodeId": 1,
    "job_id": "e8457f8f008a241deb9934929518561d",
    "mode_type": "full_pipeline",
    "mode_type_index": "full_pipeline"
  }
}

5. /mls/tool/updateMlsTask - 更新多语言任务

修改任务标题；可选传languages，传入时会将新增的输出语言在 results 中补全为待处理（status=0），并把任务整体状态置为待处理（resStatus=0）。resStatus=1（处理中）时不允许修改。

【2026-06-11 变更】若任务类型 requires_language=false（不需选语种），传 languages 将返回错误「当前任务类型不允许修改语种」。

【2026-06-30 变更】新增可选入参 param（object）：更新任务级环境变量；不传则保持原值，传 {} 表示清空为无附加变量。规则见 附录 C。resStatus=1（处理中）时不允许修改。

入参

出参

请求示例

{
  "token": "xxx",
  "episodeId": 1,
  "title": "新标题",
  "languages": "zh,en,ja"
}

请求示例（仅更新 param）

{
  "token": "xxx",
  "episodeId": 1,
  "title": "新标题",
  "param": {
    "CONSOLE_XXX": "1"
  }
}

返回示例

{
  "flag": 100,
  "flagString": "success"
}

5.1 /mls/tool/saveMlsTaskResource - 新增/编辑任务素材

在已有任务上新增或编辑前端上传素材（写入 mls_resource_file，source=upload）。

• 新增：传 episodeId、language、fileType、fileUrl。若同键（language+fileType）已有活跃记录，先软删再插入。
• 编辑：额外传原素材 id；会软删该记录（及同键活跃记录）再插入新记录。
• resStatus=1（处理中）不允许操作。

入参

出参

请求示例（新增）

{
  "token": "xxx",
  "episodeId": 1,
  "language": "original",
  "fileType": "subtitle",
  "fileUrl": "https://xxx/new.srt"
}

请求示例（编辑）

{
  "token": "xxx",
  "episodeId": 1,
  "id": 12,
  "language": "original",
  "fileType": "subtitle",
  "fileUrl": "https://xxx/replaced.srt"
}

5.2 /mls/tool/deleteMlsTaskResource - 删除任务素材

软删指定素材（is_del=1）。resStatus=1 处理中不允许删除。

入参

请求示例

{
  "token": "xxx",
  "episodeId": 1,
  "id": 12
}

6. /mls/tool/retryMlsTask - 失败重试

对失败或未完成的 AI 多语言任务重试。每次重试均生成新的 job_id 并在响应中返回。

• 需选语种（requires_language=true，含全流程）：逻辑与原先一致——不传 languages 时重置所有非成功语种；传入时仅重置指定语种。resStatus 置为 0。
• 不需选语种：仅将 resStatus 置为 0 并更新 job_id，不修改 results。

【2026-06-30 变更】无需传 param，重试沿用创建任务时写入库中的环境变量。

【2026-07-07 变更】若任务 origin_ready=0，或关联剧集视频 preprocess_status=3（预处理失败），会先自动调用 §6.1 retryMlsVideoPreprocess 逻辑重新提交预处理，再重置 AI 任务状态。预处理重试信息在响应 data.preprocess_retry 中返回。

任务已完成（resStatus=3）时不可重试。

注意：纯 AI 管道失败（源片已就绪、origin_ready=1）时仅重置任务状态，不会重复转码。

入参

出参

请求示例

{
  "token": "xxx",
  "episodeId": 1,
  "languages": "zh,en"
}

返回示例（含预处理重试）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "job_id": "a1b2c3d4e5f6789012345678abcdef01",
    "preprocess_retry": {
      "job_no": "8810bb51c848eceac22889c9dd20c58a",
      "retry_mode": "transcode"
    }
  }
}

返回示例（仅 AI 任务重试）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "job_id": "a1b2c3d4e5f6789012345678abcdef01"
  }
}

6.1 /mls/tool/retryMlsVideoPreprocess - 视频预处理失败重试

对 转码 / 网络上传 预处理流水线失败后的重试。每次重试会新建一条 mls_video_preprocess 记录。

重试策略：

成功后仍走 DMS 回调收尾：写入最终源地址 C、更新关联 mls_drama_video / mls_list、删除源片 A。详见 §19。

入参

三选一（优先级：job_no > videoId/id > episodeId）：

出参

请求示例（剧集视频）

{
  "token": "xxx",
  "videoId": 657
}

请求示例（按任务 episodeId）

{
  "token": "xxx",
  "episodeId": 1001
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "job_no": "8810bb51c848eceac22889c9dd20c58a",
    "retry_mode": "pull",
    "ref_type": "drama_video",
    "ref_id": 657,
    "message": "预处理已重新提交（仅网络上传）"
  }
}

7. /mls/tool/deleteMlsTask - 删除多语言任务（软删）

将任务标记为已删除（is_del=1），不物理删除。

【2026-07-08 变更】三级结构下，删除任务仅软删该任务本身，不会连带删除其所属集（mls_drama_video）或剧集（mls_drama）。如需删除整集，请用 §18.6 deleteMlsDramaVideo；删除整剧请用 §18.8 deleteMlsDrama。

入参

出参

请求示例

{
  "token": "xxx",
  "episodeId": 1
}

返回示例

{
  "flag": 100,
  "flagString": "success"
}

8. /mls/tool/getMaterialAccess - 获取素材上传签名参数

获取素材上传所需的签名等信息，用于直传或上传接口。

入参

出参

请求示例

{
  "token": "xxx",
  "classify": "video",
  "parentId": "01",
  "service": "private-upload",
  "subService": "mls"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "signatureNonce": "12345",
    "accessId": "xxx",
    "expireTime": 1770534000,
    "signature": "14224ad83a75b14b349300868161d726",
    "filePrefix": "material-1011-1000-",
    "diyParam": "{\"platform\":\"apaas\",\"service\":\"material-upload\",\"groupID\":\"01\",\"subUser\":\"1000\",\"subCode\":\"subId\",\"subService\":\"material\"}"
  }
}

错误示例：service非material-upload或private-upload时返回「素材所属服务错误」；用户不存在返回「用户不存在」。

8.1 视频/文件分片上传（直传上传服务）

在调用本上传接口前，需先通过 8. getMaterialAccess 获取上传签名参数（accessId、expireTime、signature、signatureNonce、filePrefix、diyParam），再向直传上传服务发起分片上传。

• 视频文件（后缀.mp4、.mkv，不区分大小写）：使用 DVR.FormUpload。
• 非视频文件：使用 MFS.APAAS.FormUpload。

当文件大小超过 10MB 时，需按 10MB 一片进行分片，按顺序逐片上传；小于等于 10MB 时视为 1 片。

接口地址

UPLOAD_URL为前端/环境配置的上传域名（upload-dvr.{DOMAIN}，如：https://upload-dvr.jstest.aodianyun.cn/v2/DVR.FormUpload），请求时需带上与站点一致的协议（如https:）。

请求方式

• Method：POST
• Content-Type：multipart/form-data

请求参数（Form 表单字段）

响应结构（JSON）

成功时，文件最终 URL 以response.data.location或response.data.data?.location为准（二者有一即可）。

分片与顺序

• 分片大小固定为 10MB（10 × 1024 × 1024 字节）。
• 最后一片可为不足 10MB 的剩余部分。
• 分片必须按chunk从 0 到chunks-1顺序上传；全部片上传成功后，最后一片的响应中返回文件 URL。

前端实现要点（参考）

1. 先请求getMaterialAccess，拿到materialAccess（accessId、expireTime、signature、signatureNonce、filePrefix、diyParam）。
2. 根据文件名后缀判断是否为视频（如.mp4、.mkv），选择 DVR.FormUpload 或 MFS.APAAS.FormUpload。
3. 使用File.slice(start, end)切分 10MB 一片，循环上传；每片 FormData 带上表中所列签名参数及 chunk、chunks、name。
4. 仅当Flag === 100时视为成功；最后一片成功响应中的location或data.location即为上传结果 URL。

9. /mls/tool/getMlsAmount - 获取当前额度（积分）

获取当前用户 MLS 额度；若尚无额度记录，按规则自动创建（首次赠送 6000 积分）。可用额度会扣除处理中未计费任务（resStatus 0/1）的预占额度。

【2026-06-11 变更】预占按每条待处理任务的 mode_type 与 languages 计算：时长 × (需选语种 ? 语种数 : 1) × 单价，单价见 getMlsModeTypeList（全流程默认 10 积分/秒）。

入参

出参

【变更】 当前版本data包含last_amount、reserved、available、invite_reward_total，不再返回month字段。

请求示例

{
  "token": "xxx"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "last_amount": 3000,
    "reserved": 0,
    "available": 3000,
    "invite_reward_total": 24000
  }
}

10. /mls/tool/getMlsAmountRunList - 额度（积分）使用记录

分页查询当前用户的 MLS 额度流水（mls_user_amount_run），按 id 倒序；每条记录可带关联任务标题 task_title（通过 episodeId 关联 mls_list）。支持按uptime时间范围和trade_type类型过滤（可选）。

入参

出参

请求示例

{
  "token": "xxx",
  "page": 1,
  "num": 15,
  "uptimeStart": 1704067200,
  "uptimeEnd": 1704153600,
  "tradeType": 2
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "id": 1,
      "uin": 12345,
      "trade_amount": "10.40",
      "last_amount": "41.60",
      "trade_type": 2,
      "trade_desc": "episodeId:5 《示例短剧》 多语言制作扣费 本次新增成功2语种 输出语种:zh,en 2分钟",
      "episodeId": 5,
      "uptime": 1704067200,
      "task_title": "示例短剧"
    }
  ],
  "total": 1
}

11. /mls/tool/checkMlsAmount - 判断额度（积分）是否充足

若无额度记录会先走分配逻辑（同 getMlsAmount）。

【2026-06-11 变更】计费规则按 mode_type 区分（配置见 getMlsModeTypeList）：

• 公式：required = max(duration, 30) × (base_price_per_second + lang_price_per_second × N + (timestamp_check ? 1 : 0))
• N：类型 requires_language=true 时为语种数，否则为 0
• timestamp_check：入参 param.CONSOLE_SUBTITLE_TIMESTAMP_CHECK 为真时开启
• 预占：与 getMlsAmount 相同，按待处理任务剩余未扣（前置/时间戳/未成功语种）累加

全流程示例（base=6, lang=3，120 秒，2 语种）：120 × (6 + 3×2) = 1440 积分。
开启时间戳校对再加 120：合计 1560。
非全流程示例（subtitle_erase_dialog，base=3）：120 × 3 = 360 积分。
不足 30 秒按 30 秒计（如 5 秒视频按 30 秒）。

入参

出参

请求示例（全流程）

{
  "token": "xxx",
  "duration": 120,
  "mode_type": "full_pipeline",
  "languages": "zh,en"
}

请求示例（非全流程）

{
  "token": "xxx",
  "duration": 120,
  "mode_type": "subtitle_erase_dialog"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "sufficient": true,
    "required": 2400,
    "last_amount": 3000,
    "reserved": 0,
    "available": 3000,
    "billable_seconds": 240,
    "language_count": 2,
    "mode_type": "full_pipeline"
  }
}

说明：扣费在 OpenTool 回调中与状态更新同一事务触发（SELECT … FOR UPDATE 锁任务行 + 锁额度行）——全流程 updateMlsResult / 需语种非全流程 updateMlsJobStatus：首次成功扣前置（及时间戳校对加价），每个新成功语种扣叠加费；不需语种任务成功时扣前置（及时间戳）。已扣标记不重扣；后付费无退费。若用户开启成片审核，全流程成功结果可能以 status=4 入库，扣费仍在首次成功时发生。deductMlsAmount 为内部逻辑，不单独对外暴露。

12.0 /mls/tool/checkToken - 校验 / 换取登录态

【更新，更新时间：2026-07-23】免登录接口。根据 subToken 形态走两条路径：

1. 普通 MLS 会话：subToken 不以 apaas 开头 → 从 Redis 读取会话；存在则返回用户信息，不存在返回未登录。
2. apaas 控制台换票：subToken 以 apaas 开头 → 请求控制台 checkToolAccess；必要时补全 MLS 账号后签发新的 MLS subToken。

入参

环境变量

分支说明

A. 普通会话校验（非 apaas 前缀）

• Redis 命中 → flag=100；未命中 → flag=200「您还未登录」；subToken 空 → flag=110。

B. apaas 换票（apaas 前缀）

1. 调用 checkToolAccess（subType=mls）：
   • sourceFrom=ady → http://apaas-api.aodianyun.com/...
   • 否则 → http://apaas-api.{DOMAIN}/...
2. 取 extId：优先 parentUin，否则 userId。

B1. sourceFrom=ady（渠道用户）

1. 仅按 platform_user_key 查用户。
2. 查不到 → createMlsUserWithIpaas 新建 uin，写入 platform_code / platform_user_key / source（渠道来源）。
3. 签发登录态。渠道用户创建任务等不强制绑手机。

B2. 非 ady（普通用户）

1. uin = extId，仅按 uin 查 mls_user。
2. 不存在则补全必要信息（复用 apaas uin）：source=apaas，不写 platform_code / platform_user_key；初始化 DMS、积分账户。
3. 签发登录态。

出参

请求示例

普通会话校验：

{
  "subToken": "a1b2c3d4e5f6..."
}

apaas 控制台换票（原逻辑）：

{
  "subToken": "apaascc3809defc8c71847da70b225029aa23"
}

ADY 换票（sourceFrom=ady）：

{
  "subToken": "apaascc3809defc8c71847da70b225029aa23",
  "sourceFrom": "ady"
}

返回示例（普通会话成功）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "uin": 12345,
    "phone": "13800138000",
    "username": "用户xxx",
    "avatar": "",
    "parentId": "01",
    "parentUin": 12345,
    "locale_code": "zh-cn",
    "Token": "a1b2c3d4e5f6...",
    "userId": 12345
  }
}

返回示例（apaas 换票成功 · 渠道 ady）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "uin": 10001111,
    "phone": null,
    "username": "用户10001111",
    "realname": "用户10001111",
    "parentId": "01",
    "parentUin": 10001111,
    "source": "partner_ady_gw",
    "platform_code": "partner_ady_gw",
    "platform_user_key": "partner_ady_gw_2088",
    "Token": "新签发的mls_token",
    "subToken": "新签发的mls_token",
    "userId": 10001111
  }
}

返回示例（apaas 换票成功 · 普通用户）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "uin": 2088,
    "phone": null,
    "username": "用户2088",
    "source": "apaas",
    "platform_code": "",
    "platform_user_key": null,
    "Token": "新签发的mls_token",
    "subToken": "新签发的mls_token",
    "userId": 2088
  }
}

说明：渠道示例中 platform_code 以 MLS_ADY_PLATFORM_CODE + _gw 为准；普通用户无渠道字段。

返回示例（未登录 / 参数错误）

{
  "flag": 200,
  "flagString": "您还未登录"
}

{
  "flag": 110,
  "flagString": "服务token不能为空"
}

前端对接提示

• 从 apaas 控制台带 apaas… 进入曜幕时：先调本接口换票，拿到 data.subToken（或 data.Token）后，再作为后续接口的 token。
• 来自 ADY（aodianyun.com）入口时传 sourceFrom=ady。
• 本接口在网关 NO_TOKEN_CMDS 中，不要再传业务 token 字段做网关鉴权。
• 与 §12.6.1 getUserInfo 区别：getUserInfo 用已登录的 token 读会话；checkToken 用 subToken 校验或完成 apaas→MLS 换票。

12. /mls/tool/login - 登录

【修改，更新时间：2026-03-24】 当前实现支持 3 种登录方式：

• 手机号 + 密码
• uin + 密码
• 手机号 + 短信验证码

其中“手机号 + 短信验证码”模式下，若手机号未注册会自动创建账号后登录。

登录成功后返回subToken（后端在 Redis 中保存用户会话信息）。本接口为免登录接口，无需传 token。

入参

账号判定规则

当smsCode为空时：

• username为纯数字且不符合手机号格式时，按uin + 密码登录
• 否则按手机号 + 密码登录

出参

说明：登录成功后用户完整资料（含 platform_code / platform_user_key / hasPassword）写入 Redis；请用 §12.6.1 getUserInfo（或换票接口返回的会话）读取。渠道用户（platform_code 非空）可用 §12.6.2 getChannelPlatformInfo 查充值跳转地址。hasPassword 的前端判断约定见 §12.6.1。

请求示例

{
  "username": "13800138000",
  "userPassword": "front_encrypted_password"
}

手机号 + 短信验证码：

{
  "username": "13800138000",
  "smsCode": "123456"
}

uin + 密码：

{
  "username": "10001111",
  "userPassword": "front_encrypted_password"
}

返回示例

{
  "flag": 100,
  "flagString": "登录成功",
  "data": {
    "subToken": "md5_token_string"
  }
}

12.1 /mls/mlsUser/generateCaptcha - 生成图形验证码

【新增，更新时间：2026-03-23】 生成图片验证码。验证码内容与check_key拼接后存 Redis（5 分钟有效）。

说明：滑块/行为验证码由前端按平台文档接入，拿到captchaId后直接调用sendSmsCode传captchaId，无需调用本接口。本接口为传统图形码，后续可能下线。

入参

出参

返回 JPEG 图片流（content-type: image/jpeg），非 JSON。

12.2 /mls/mlsUser/sendSmsCode - 发送短信验证码

【更新时间：2026-04-07】 先发码前人机校验，支持两种方式（二选一）：

1. 滑块/行为验证码：传captchaId（前端完成验证后获得的唯一 id）。服务端请求MLS_CAPTCHA_VERIFY_BASE+/v1/message/Captcha/query?captcha_id=...做二次校验，参见 广电云平台验证码·服务端校验。
2. 传统图形验证码：传check_key+captcha（与generateCaptcha配套），Redis 一次性校验（逐步废弃）。

入参

业务规则

• module=register：手机号必须未注册
• module=login：允许未注册手机号（用于短信登录自动注册）
• module=password：手机号必须已注册
• 使用图形码时：校验通过后 Redis 中对应 key 即删除（一次性）
• 使用captchaId时：须在运行环境配置MLS_CAPTCHA_VERIFY_BASE（验证码服务根地址，无末尾斜杠，例如https://message.guangdianyun.tv）

返回示例

{
  "flag": 100,
  "flagString": "发送成功"
}

12.3 /mls/mlsUser/register - 注册

【新增，更新时间：2026-03-23】 手机号注册，需短信验证码校验通过。

入参

说明

• 注册时会先调用外部账户服务创建底层账号并获取uin
• mls_user.password入库使用PASSWORD('{$password}')

12.4 /mls/mlsUser/changePassword - 已登录修改密码

【更新，更新时间：2026-07-24】 已登录用户修改密码（当前版本不要求旧密码）。

入参

说明

• 若用户原先未设置密码（mls_user.password 为空/NULL），设置成功后会刷新当前 token 对应的 Redis 会话，将 hasPassword 补为 true，无需重新登录即可从 getUserInfo 读到最新值。
• 若原先已有密码，仅更新密码哈希，不额外改写会话中的 hasPassword（已为 true）。

12.5 /mls/mlsUser/resetPassword - 忘记密码重置

【新增，更新时间：2026-03-23】 未登录场景，通过手机号 + 短信验证码重置密码。

入参

说明

• 本接口为免登录接口
• 校验短信验证码后更新密码（当前实现为直接写入前端加密值）

12.5.1 /mls/mlsUser/bindPhone - 绑定手机号（微信未绑定用户）

【新增，更新时间：2026-03-24】 适用于微信登录后账号未绑定手机号的场景。已被其他账号注册的手机号不允许绑定。

入参

业务规则

• 仅允许当前账号phone为空时绑定
• 手机号格式必须符合^1\\d{10}$
• 目标手机号必须未注册

返回示例

{
  "flag": 100,
  "flagString": "绑定成功"
}

12.5.2 /mls/mlsUser/changePhone - 修改手机号（已绑定用户）

【新增，更新时间：2026-03-24】 已登录且已有手机号的用户修改手机号。新手机号若已注册则不允许修改。

入参

业务规则

• 当前账号必须已绑定手机号
• 新手机号不能与当前手机号相同
• 手机号格式必须符合^1\\d{10}$
• 新手机号必须未注册

返回示例

{
  "flag": 100,
  "flagString": "修改成功"
}

12.5.2.1 /mls/mlsUser/updateAvatar - 修改头像

【新增，更新时间：2026-04-07】 已登录用户更新mls_user.avatar。成功后刷新当前 token 对应的 Redis 会话，避免getUserInfo读到旧头像。

入参

返回示例

{
  "flag": 100,
  "flagString": "修改成功"
}

12.5.2.2 /mls/mlsUser/updateProfile - 修改基础资料

【更新时间：2026-04-07】 已登录用户更新资料字段：仅处理请求体里出现的键，未传的字段不修改。至少传下列之一：username、realname、company、email。成功后刷新当前 token 的 Redis 会话。

说明：mls_user表中无nickname列，昵称使用username字段；本接口只接收参数名username。

入参

返回示例

{
  "flag": 100,
  "flagString": "修改成功"
}

12.5.2.3 /mls/mlsUser/getMlsI18nLocaleList - 获取 App 界面语言列表

【新增，更新时间：2026-05-09】从 apaas.mls_admin_ui_locale 读取界面国际化可选语言（语言名称 + 语言码），供 App 语言切换展示。与 1 getSupportLanguageList（任务翻译语种、mls_languages + mls_user_conf）数据源与用途不同。

登录：本命令不在网关 NO_TOKEN_CMDS 中，须传有效 token（与其它需登录的 mlsUser 接口一致）。

查询条件：enable = 1。排序：sort_order 升序（NULL 会排在 MySQL 默认顺序中，配置时请填具体序号）。

入参

出参

请求示例

{
  "token": "xxx"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "locale_code": "zh-CN",
      "locale_name": "简体中文"
    },
    {
      "locale_code": "en-US",
      "locale_name": "English"
    }
  ]
}

12.5.2.4 /mls/mlsUser/updateUserLocale - 更新用户界面语言码

【新增，更新时间：2026-05-09】已登录用户更新 apaas.mls_user.locale_code。入参语言码须在 mls_admin_ui_locale 中存在且 enable = 1。成功后调用 refreshMlsUserRedisSession，刷新当前 token 对应 Redis 会话，保证 getUserInfo 读到最新 locale_code。

登录：须传 token；uin 由网关在校验 token 后注入，客户端一般无需在 body 重复传 uin。

入参

出参

请求示例

{
  "token": "xxx",
  "locale_code": "zh-CN"
}

返回示例

{
  "flag": 100,
  "flagString": "更新成功"
}

12.5.3 /mls/mlsUser/getInviteRecordList - 邀请记录列表

【更新时间：2026-04-07】 分页查询当前用户邀请记录；列表项连表返回被邀请人基础信息；支持按状态、被邀请人、创建时间筛选。

说明：/mls/index网关在校验 token 后会自动把当前登录用户的uin写入请求参数，业务侧按邀请人 uin 过滤；客户端一般只需传token及下方筛选参数。

入参

排序规则：create_time倒序，id倒序（同一时间戳下分页稳定）。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "id": 1,
      "inviter_uin": 1001,
      "invitee_uin": 2001,
      "reward_points": 2000,
      "status": 1,
      "create_time": 1710000000,
      "update_time": 1710000000
      "invitee_username": "昵称或用户名",
      "invitee_avatar": "https://...",
      "invitee_company": ""
    }
  ],
  "total": 1
}

说明：invitee_username、invitee_avatar、invitee_company来自mls_user左连接；未返回手机号等敏感字段。若用户无对应行则上述字段为null。

邀请功能 SQL 变更

邀请功能数据库变更脚本已提供在：

• code/apaasTool/api/tool/mls_invite_schema.sql

包含：

• mls_user_amount新增invite_reward_total
• 新建mls_user_invite_record（含invitee_uin唯一索引，防止重复发奖）

12.5.4 /mls/mlsUser/getUserConf - 获取用户配置

【新增，更新时间：2026-04-08】 获取用户配置。返回结构统一：始终返回config（默认配置与用户配置合并结果）。

存储设计：mls_user_conf表每个uin一条记录，config字段为 JSON。接口返回为“默认配置 + 用户配置”的合并结果。用户配置的写入由管理后台维护，本服务仅提供读取。

入参

出参（统一结构）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "uin": 1001,
    "type": "all",
    "config": {
      "languages": "basic",
      "batch_review": false,
      "duration_limit": 5
    }
  }
}

说明：

• 不论type是否传入，data都统一返回config字段
• 当type=all（或不传）时，data.type返回all
• 当type传单项（如duration_limit）时，data.type返回该单项，但config仍返回全量配置
• 默认值：languages=basic、batch_review=false、duration_limit=5
• type传不支持值时返回参数错误
• batch_review：为true时，管道回调在成片成功时会先以 待审核（results.status=4） 写入任务（详见附录 A）；管理后台审核通过后再变为成功(2)并重算任务resStatus。

12.6 /mls/tool/logout - 退出登录

【新增，更新时间：2026-03-23】 退出登录并删除 Redis 中 token 对应会话数据。

说明：路径为 /mls/mlsUser/... 且本章已列出的接口由 mlsUser.php 实现；12.6 logout 等为 mls.php，路径为 /mls/tool/...。

入参

返回示例

{
  "flag": 100,
  "flagString": "退出成功"
}

12.6.1 /mls/tool/getUserInfo - 获取当前登录用户信息

【更新，更新时间：2026-07-24】从 Redis 读取当前token对应的用户会话信息并返回。

会话内容来自 mls_user 行（登录 / 换票 / 微信等签发时写入），已包含渠道归属字段 platform_code、platform_user_key（普通用户一般为空），以及是否已设置密码字段 hasPassword。

入参

出参（data 主要字段）

hasPassword 兼容说明（前端必读）

• 本字段上线后新签发的登录态（手机号/验证码/密码、微信、渠道 SSO、apaas 换票等）都会带上 hasPassword。
• 上线前已登录、尚未重新登录的旧会话没有该字段（undefined / 不存在）。
• 前端判断「未设置密码」的约定：仅当 hasPassword 字段存在且值为 false 时，才视为未设置密码；字段缺失时不要引导设密，可等待用户重新登录或走会刷新会话的接口后再读。
• 用户通过 §12.4 changePassword 首次设密成功后，当前会话会刷新为 hasPassword=true。

伪代码示例：

const needSetPassword = Object.prototype.hasOwnProperty.call(userInfo, 'hasPassword')
  && userInfo.hasPassword === false;

未登录或 token 无效：

• flag=200
• flagString="您还未登录"

返回示例（成功 · 含渠道字段）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "uin": 12345,
    "phone": "13800138000",
    "wxUnionId": "xxxx",
    "wxMpOpenId": "xxxx",
    "wxMiniOpenId": "xxxx",
    "avatar": "https://xxx/avatar.jpg",
    "company": "xxx",
    "email": "xxx",
    "parentId": "01",
    "parentUin": 12345,
    "realname": "xxx",
    "username": "xxxx",
    "createTime": 1700000000,
    "locale_code": "zh-cn",
    "source": "partner_ady_gw",
    "platform_code": "partner_ady_gw",
    "platform_user_key": "partner_ady_gw_2088",
    "hasPassword": false,
    "Token": "当前 token",
    "userId": 12345
  }
}

前端若 platform_code 非空，可再调 §12.6.3 getPayEntryConfig（当前用户充值入口）或 §12.6.2 getChannelPlatformInfo（按 code 查渠道信息）判断是否跳转外部充值页。

返回示例（未登录）

{
  "flag": 200,
  "flagString": "您还未登录"
}

12.6.2 /mls/tool/getChannelPlatformInfo - 按 platform_code 查渠道基础信息

【新增，更新时间：2026-07-23】需登录。按渠道标识查询 mls_external_platform 基础信息（不含 app_secret），供前端判断是否跳转外部充值地址。结果走 Redis 缓存（命中约 300s；不存在约 60s 负缓存）。

与 §12.6.3 getPayEntryConfig 区别：本接口按入参 platform_code 查任意渠道配置；getPayEntryConfig 固定取当前登录用户归属渠道（内部同样走该缓存）。

入参

出参

请求示例

{
  "token": "xxx",
  "platform_code": "partner_ady_gw"
}

仅用登录用户归属（会话已有 platform_code）：

{
  "token": "xxx"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "platformCode": "partner_ady_gw",
    "platformName": "奥点云官网",
    "payRedirectUrl": "https://pay.example.com/recharge",
    "status": 1,
    "useExternalPay": true
  }
}

无外部充值（走本地）：

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "platformCode": "partner_a",
    "platformName": "渠道A",
    "payRedirectUrl": "",
    "status": 1,
    "useExternalPay": false
  }
}

前端建议

1. getUserInfo / 换票结果取出 platform_code
2. 非空则可调本接口或 §12.6.3 getPayEntryConfig；useExternalPay === true 时跳转 payRedirectUrl，否则走本地充值

12.6.3 /mls/tool/getPayEntryConfig - 当前用户充值入口配置

【补充文档，更新时间：2026-07-23】需登录。按当前登录用户在 mls_user 上的 platform_code 查询渠道充值入口：有外部跳转地址则走渠道充值，否则走本地充值。

渠道配置查询走与 §12.6.2 相同的 Redis 缓存（约 300s）。本接口不需要前端再传 platform_code。

入参

出参

请求示例

{
  "token": "xxx"
}

返回示例（外部充值）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "platformCode": "partner_ady_gw",
    "platformUserKey": "partner_ady_gw_2088",
    "payRedirectUrl": "https://pay.example.com/recharge",
    "useExternalPay": true
  }
}

返回示例（本地充值）

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "platformCode": "",
    "platformUserKey": "",
    "payRedirectUrl": "",
    "useExternalPay": false
  }
}

与 getChannelPlatformInfo 怎么选

说明：本地下单不扣渠道积分；仅外部渠道充值回调（payType=3）扣渠道积分并进月对账单。

12.7 /mls/mlsUser/getWechatMpAuthUrl - 获取微信公众号授权链接

用于移动端 H5 进入微信 OAuth2 授权页。

入参

说明：

• redirectUri与afterLoginUrl都会做域名校验：其 host 必须等于DOMAIN或属于其子域名。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "authUrl": "https://open.weixin.qq.com/connect/oauth2/authorize?...",
    "scope": "snsapi_userinfo"
  }
}

12.7.1 /mls/mlsUser/getWechatJsSdkConfig - 微信 JS-SDK 签名（分享等）

前端在微信内置浏览器内引入jssdk，调用wx.config前需向后端索取签名。本接口使用公众号 cgi-bin 的access_token换取jsapi_ticket并做 SHA1 签名（与网页 OAuth 的 access_token 不是同一类）。

入参

域名校验：url的 host 必须等于环境变量DOMAIN或为其子域名（与getWechatMpAuthUrl的redirectUri规则一致）。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "appId": "wx...",
    "timestamp": 1710000000,
    "nonceStr": "abc123...",
    "signature": "sha1_hex..."
  }
}

前端示例：wx.config({ appId, timestamp, nonceStr, signature, jsApiList: ['updateAppMessageShareData', 'updateTimelineShareData'] })（具体 API 以微信文档为准）。

说明：服务端会缓存jsapi_ticket（Redis），避免频繁请求微信接口。

12.8 /mls/mlsUser/wechatMpLoginByCode - 微信 code 登录

前端已拿到微信code后，直接调用本接口换取subToken。逻辑：微信已注册 => 直接登录；未注册 => 自动补全账号并登录（phone为空，不再生成虚拟手机号）。

入参

返回示例

{
  "flag": 100,
  "flagString": "登录成功",
  "data": {
    "subToken": "md5_token_string"
  }
}

表结构说明：若要支持微信用户不填手机号，建议将mls_user.phone调整为可空，并按业务需要调整唯一索引（避免空值约束冲突）。

12.9 /mls/mlsUser/wechatMpAuthCallback - 微信授权回调

微信公众号后台 OAuth 回调地址。可直接返回 JSON；若 state 中携带了afterLoginUrl，会自动 302 跳转并附带subToken。

入参

附录 B：NO_TOKEN_CMDS 免登录接口与本文档对照

以下与网关 code/apaasTool/mls/index.php 中 NO_TOKEN_CMDS 逐项对齐。说明：

• 免登录指网关不强制校验 token；部分接口仍可根据业务在请求体传 token（如 shareMlsWorks 带 token 可记录分享用户）。

已下线（2026-06-12，临时 MLS 管理页）：getMlsTaskList、approveMlsResultReview、getMlsUserConf、setMlsUserConf、getMlsAccessForUin。对应能力改由管理后台或其它服务提供；网关 NO_TOKEN_CMDS 与业务实现均已移除。

附录 A：OpenTool mls/updateMlsResult（管道结果回调，签名校验）

本接口走openTool网关（请求头X-AccessId、X-TimeStamp、X-Signature、X-SignatureNonce等，与项目内其他 openTool 接口一致），不是/mls/index.php的免登录路由。本文档不展开 openTool 鉴权细节；以下为业务字段与状态约定。

作用

多语言处理服务向业务侧回写某任务的各语种处理结果，合并写入apaas.mls_list.results，并可能触发积分扣费。

请求体（JSON）

管道上报的status语义：0 待处理，1 处理中，2 成功，3 失败。

存储侧扩展：status = 4（待审核）

当任务所属用户的mls_user_conf中batch_review为 true（读取结果带 Redis 缓存，约 5 分钟；管理后台修改配置并保存后会清除该缓存）时：

• 对本次回调中「新成功」的语种（该语种合并前在库中状态不是 2）：入库时status记为 4（待审核），而不是 2。
• 积分扣费仍按管道上报的 成功(2) 且「此前非成功」统计，与是否写入 4 无关。
• 若本请求中发生了上述 2→4 降级，则本次更新不修改mls_list.resStatus（保持回调前任务总状态）；其余情况按合并后的results重算resStatus。
• resStatus与单条status的汇总规则中，4 视为未结案（不视为已完成），直至该语种被置为 2（例如管理后台审核通过）。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "resStatus": 1,
    "deduct": true
  }
}

支付相关（商品 / 订单 / 微信与支付宝）

支付能力依赖系统环境变量配置，部署时在 Web 服务器或 PHP 环境中设置以下变量。

环境变量说明

• 微信支付：使用 Pay SDK（pay-php-sdk）V2 接口（unifiedorder）。
• 支付宝：扫码支付（当面付 precreate）与异步通知验签使用支付宝官方 EasySDK（alipaysdk/easysdk）；电脑网站支付（form 跳转）仍使用 Pay SDK。环境变量与现有一致，无需变更。后续可扩展手机端唤起支付宝 App 支付（EasySDK 支持Factory::payment()->app()->pay(...)）。

微信支付

微信公众号授权登录（H5）

短信前置验证码（sendSmsCode 使用 captchaId 时）

说明：当前代码未引入专门“微信登录 SDK”，采用微信官方 OAuth2 接口（open.weixin.qq.com、api.weixin.qq.com）并在项目内做了轻量封装。

支付宝

上述支付宝环境变量同时用于 EasySDK（扫码、回调）与 Pay SDK（网页支付），配置一次即可。

支付宝报「验签出错 / isv.invalid-signature」时：

1. 登录 支付宝开放平台→ 控制台 → 你的应用 → 开发信息 → 接口加签方式。
2. 确认已配置 应用公钥（与代码里用的MLS_ALIPAY_PRIVATE_KEY私钥成对）：用该私钥导出公钥，在开放平台「设置应用公钥」处粘贴（通常为去掉-----BEGIN/END PUBLIC KEY-----和换行的一行）。
3. 应用公钥是「我们自己的公钥」供支付宝验我们请求；支付宝公钥是「支付宝的公钥」供我们验回调，二者不要混用。
4. 商品名称（subject）中不要含反斜杠\、双引号等，否则可能造成签名字符串不一致；代码已对 subject 做过滤。

数据库

• 支付表mls_pay_data需有字段points（购买积分，下单时写入，回调时从该字段读积分更新到mls_user_amount）。若尚未添加可执行：

ALTER TABLE mls_pay_data ADD COLUMN points int(10) UNSIGNED NOT NULL DEFAULT 0 COMMENT '购买积分' AFTER amount;

• 下单与支付仅使用mls_pay_data，不再依赖mls_order表；若业务无需独立订单表，可不再使用或删除mls_order。

13. /mls/tool/getMlsGoodsList - 获取商品列表

获取已启用的 MLS 商品列表（用于下单前展示）。

入参

需登录，可无额外参数（传token即可）。

出参

14. /mls/tool/createMlsOrderAndPay - 下单并获取支付凭证（推荐）

一个接口完成下单 + 获取支付二维码/链接，前端只需请求一次即可拿到订单信息与支付数据。

入参

出参

返回为 订单信息 + 支付数据 合并：payDataId、outTradeNo、amount、payType、goodsName、points、existingOrder（若有），以及按支付方式：

• 微信 PC：code_url→ 用二维码库生成二维码，用户微信扫码支付
• 微信内 JSAPI：appId、timeStamp、nonceStr、package、signType、paySign→ 调微信 JSSDK 调起支付
• 支付宝 PC（默认）：qr_code→ 用二维码库生成二维码，用户打开支付宝 App 扫码支付
• 支付宝 PC（网页跳转）：传alipayScene=page时返回form_html→ 新窗口写入并提交：var w = window.open('', '_blank'); w.document.write(data.form_html); w.document.close();

15. /mls/tool/createMlsOrder - 下单

仅创建支付记录（mls_pay_data，含points）。同账户同商品 2 小时内未支付则复用该支付单。返回payDataId、outTradeNo等，用于后续调 submitMlsPay。

入参

出参

16. /mls/tool/submitMlsPay - 提交支付

根据下单结果调起支付：PC 端微信返回code_url，支付宝默认返回qr_code（扫码）；传alipayScene=page时支付宝返回form_html（网页跳转）。

入参

出参

按支付方式返回：

• 微信 NATIVE（PC）：data.code_url→ 生成二维码，用户微信扫码
• 微信 JSAPI（微信内）：data含appId、timeStamp、nonceStr、package、signType、paySign，用于前端调起微信支付
• 支付宝扫码（默认）：data.qr_code→ 生成二维码，用户打开支付宝 App 扫码
• 支付宝网页：传alipayScene=page时返回data.form_html→ 新窗口写入并提交：var w = window.open('', '_blank'); w.document.write(data.form_html); w.document.close();

支付完成回调（免登录）

由微信/支付宝服务器 POST 调用，无需 token。

• 微信异步通知：POST /mls/tool/wechatPayNotify（配置微信商户平台「支付结果通知 URL」为该地址）。
• 支付宝异步通知：POST /mls/tool/alipayPayNotify（下单时传入的notify_url为该地址）。

验签通过且订单状态为成功/完成后，系统会：

1. 更新mls_pay_data状态，从该表points字段读取购买积分；
2. 增加mls_user_amount额度并写入mls_user_amount_run流水（trade_type=2 积分充值）；
3. 向 DMS 推送一条消息，便于下游（如站内信、推送）处理。

前端域名引入域名：wss://mqttdms.{DOMAIN}:8300/mqtt，如：wss://mqttdms.jstest.aodianyun.cn.cn:8300/mqtt

DMS 推送内容

{
  "uin": 123,
  "points": 1000,
  "tradeDesc": "积分充值",
  "payType": 1,
  "payDataId": 456,
  "status": 1,
  "message": "success"
}

17. /mls/tool/collectOperationLog - 上报操作日志

已登录用户上报前端操作行为；网关 mls/index.php 在校验 token 后转发。成功后将异步 POST 至 OPERATION_HOST 下的采集服务（见 code/apaasTool/mls/operation_log.inc.php）。

入参

出参

请求示例

{
  "token": "xxx",
  "moduleName": "任务管理",
  "actionName": "下载",
  "requestData": "{\\"type\\":\\"原片\\"}"
}

返回示例

{
  "flag": 100,
  "flagString": "success"
}

18. 剧集管理（drama）

剧集用于批量管理多集视频：创建时不选任务类型，在首次 submitMlsDramaTasks 时选择并写入剧集；后续新增视频再提交时自动使用剧集已存的 mode_types（前端可根据 mode_types 是否为空 / mode_types_configured 控制是否只读）。

【2026-06-24 变更摘要】

• 新增剧集 CRUD、视频上传、批量提交接口。
• 创建剧集仅需 name；mode_types / languages 在首次提交任务时传入并持久化到剧集。
• mode_types 支持逗号分隔多类型（full_pipeline 不可与其他类型共存）。
• 再次提交：以剧集已存 mode_types、languages 为准做增量；若请求中传入与库不一致的类型/语种则拒绝。
• submitMlsDramaTasks 事务内全成功或全失败；删除视频（deleteMlsDramaVideo）时会级联软删该集下全部任务，存在处理中（resStatus=1）任务时拒绝删除。

【2026-07-07 变更摘要】视频预处理

• addMlsDramaVideo 上传后若源片超规格则自动启动预处理（见 §19）。
• videos 列表返回 origin_ready、preprocess_status、preprocess_fail_msg。
• 批量提交时允许预处理中的视频先创建任务（origin_ready=0）；预处理完成后自动同步源地址。
• 某视频 preprocess_status=3 时 submitMlsDramaTasks 拒绝并提示调用 §6.1 retryMlsVideoPreprocess。

18.1 /mls/tool/addMlsDrama - 创建剧集

返回 data.dramaId；mode_types、languages 初始为空。

18.2 /mls/tool/updateMlsDrama - 更新剧集

支持修改名称与备注；任务类型请在 submitMlsDramaTasks 首次提交时确定。

18.3 /mls/tool/getMlsDramaList - 剧集列表

返回 data.list（含 video_count、source_type、remark）、data.count。

18.4 /mls/tool/getMlsDramaDetail - 剧集详情

返回剧集信息及 videos 列表（每条含 tasks、task_count）。

videos[] 单条视频字段补充：

tasks[] 任务字段（getMlsDramaDetail / getMlsEpisodeList / getMlsEpisodeDetail 均返回）：

18.4.1 /mls/tool/getMlsEpisodeList - 集（视频）列表

返回 data.list（含 tasks、task_count、drama_name）、data.count。tasks[] 字段见 §18.4 tasks[] 任务字段。

18.4.2 /mls/tool/getMlsEpisodeDetail - 集详情

返回集信息及完整 tasks[]（字段见 §18.4 tasks[] 任务字段）。

18.4.3 /mls/tool/updateMlsEpisode - 更新集名称

18.5 /mls/tool/addMlsDramaVideo - 上传视频到剧集

服务端会查询媒资信息并判定是否需预处理（§19）。需预处理时写入 origin_ready=0、preprocess_status=1 并异步启动流水线；不需预处理时 origin_ready=1。预处理提交失败返回 flag=110 且 preprocess_status=3。

18.6 /mls/tool/deleteMlsDramaVideo - 删除集（视频）

规则：若存在 处理中（resStatus=1）任务，返回 110；否则级联软删该集下全部任务后删除集。

18.7 /mls/tool/submitMlsDramaTasks - 批量提交任务

首次提交（剧集 mode_types 为空）：使用入参 mode_types / languages 创建任务，成功后写入剧集。

再次提交（剧集 mode_types 非空）：使用剧集已存配置，对尚未提交的视频 × 各类型做增量；请求体中的类型/语种若与库不一致返回 110。

若任一下属视频 preprocess_status=3，整批返回 110：视频「xxx」预处理失败，请重试预处理或删除后重新上传。

额度不足或任一步失败则整批回滚。

请求示例（带 param）：

{
  "token": "xxx",
  "dramaId": 1001,
  "mode_types": "audio_separate,subtitle_erase_dialog",
  "param": {
    "CONSOLE_XXX": "1"
  }
}

返回示例：

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "created": [
      {"videoId": 1, "videoTitle": "第1集", "mode_type": "audio_separate", "episodeId": 101, "job_id": "..."}
    ],
    "created_count": 1,
    "mode_types": "audio_separate,subtitle_erase_dialog",
    "languages": "",
    "first_submit": true
  }
}

18.8 /mls/tool/deleteMlsDrama - 删除剧集

软删剧集及下属视频；若存在活跃关联任务则拒绝。

19. 视频预处理（转码 + 网络上传）

用户上传的源视频地址记为 A。若不符合 AI 处理规格，后台异步执行：

A（用户上传）→ 转码产出 B → submitJobs PULL → 入库完成 C → 删除 A

B 为中间转码文件，C 为写入业务表的最终 origin_url；B 由媒资侧随 A 一并清理。

19.1 触发条件（满足任一即预处理）

判定依赖 MSS getUserUploadDvr 返回的媒资信息。

19.2 启动时机

同一视频（drama_video）只挂一条活跃预处理 job；单任务无剧集视频时 ref 为 task + episodeId。

19.3 状态字段

mls_list.origin_ready

mls_drama_video

mls_video_preprocess.status（内部任务表，运维排查用）

19.4 失败与重试

• 预处理失败：关联任务 resStatus=4、origin_ready=0；剧集视频 preprocess_status=3。
• 重试接口：§6.1 retryMlsVideoPreprocess；或在 §6 retryMlsTask 时自动连带。
• AI 管道失败（源片已就绪）仅用 retryMlsTask，不会重复转码。

19.5 DMS 回调（运维）

用户注册时初始化 DMS 并注册以下免登录回调（网关 NO_TOKEN_CMDS）：

老用户需执行 initMlsUserDmsBatch（内网/运维，MLS_ALLOW_DMS_BATCH_INIT 环境变量控制）。详见 code/apaasTool/scripts/mls_init_user_dms.md。

数据库迁移脚本：code/apaasTool/sql/mls_video_preprocess.sql。

19.6 涉及接口一览

管理后台 Go 服务通过 HTTP 调用上述两个内网接口；补偿也可由 cron 定时 POST /mls/tool/runMlsVideoPreprocessCompensation。

附录 C：任务级环境变量 param

param 为任务级环境变量：创建任务时由前端传入，持久化在 mls_list.param；处理节点通过 OpenTool getUserMlsTaskList 拉取待处理任务时拿到该对象，并作为各阶段 Docker 容器的 -e KEY=VALUE 环境变量。无特殊配置时不传或传 {} 即可（与老任务兼容）。

字段定义

值类型

• 支持：string、number、boolean
• 不支持：嵌套 object / array（传了返回 flag=110）

键名规则

• 须符合环境变量命名：以字母或下划线开头，仅含字母、数字、下划线
• 不符合规则的键：服务端静默丢弃（不报错）
• 以下保留键会被静默丢弃（由处理节点按负载注入）：DEMUCS_URL、LEMAS_TTS_URL、CHATTRBOX_TTS、TTS_URL_01、TTS_URL_02、AVPS_CACHE_PATH

涉及接口

示例

{
  "CONSOLE_ADAPTIVE_TIME_LEN": false,
  "CONSOLE_XXX": "1"
}

错误码

数据库变更

上线前需在 mls_list 执行迁移脚本 code/apaasTool/sql/mls_list_param.sql（MySQL 5.7 下 TEXT 不能写 DEFAULT，脚本已分步处理）：

ALTER TABLE `mls_list`
  ADD COLUMN `param` text NULL COMMENT '任务级环境变量 JSON 对象' AFTER `job_id`;

UPDATE `mls_list` SET `param` = '{}' WHERE `param` IS NULL OR TRIM(`param`) = '';

ALTER TABLE `mls_list`
  MODIFY COLUMN `param` text NOT NULL COMMENT '任务级环境变量 JSON 对象';

外部平台打通

上线前执行：

• sql/mls_external_platform.sql（首次）
• sql/mls_channel_points_alter.sql（渠道积分账户 / 月对账单增量）
• sql/mls_user_password_nullable.sql（password 允许为空，渠道/微信注册不再写默认密码）

给外部渠道的对接文档（可直接外发）： mls_channel_open_api.md

内部摘要

• SSO：POST /mls/mlsUser/ssoLogin（可不传手机号；不生成默认密码）
• 充值回调：POST /mls/tool/externalPointsRecharge（只传积分；金额按渠道 settle_price 换算；不对外返回单价）
• 可用积分：POST /mls/tool/getChannelAvailablePoints
• 租户信息：POST /mls/tool/getChannelTenantInfo（按 platform_user_key 查用户基础信息与积分）
• 手机号：platform_code 非空的渠道用户，创建任务/上传等不强制绑手机；微信/官网等仍强制
• C 端入口：
  • POST /mls/tool/getPayEntryConfig（§12.6.3，需登录，取当前用户归属渠道充值入口）
  • POST /mls/tool/getChannelPlatformInfo（§12.6.2，需登录，按 platform_code 查渠道基础信息）
• 本地下单不扣渠道积分，仅 payType=3 扣渠道积分并进月对账单
• 登录会话：getUserInfo 等返回 platform_code、platform_user_key（渠道用户非空）、hasPassword（是否已设密码；旧会话可能无此字段）
• 对账单：每渠道每月一条，按天汇总刷新；仅统计 payType=3 成功单