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

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

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

【2026-09-23 变更摘要】用户反馈补齐关单 / 追评回流

• 新增 closeMyMlsFeedback：用户关闭本人工单（status=closed，写 close_time，清未读；可选 remark；不可重开）。
• appendMlsFeedbackMessage：若当前为 replied，追评后自动回到 processing，便于后台重新跟进。

【2026-09-22 变更摘要】用户反馈 / 工单（C 端）

新增接口（路径均为 POST /mls/tool/...，须登录；uin 以网关注入的 parentUin / uin / userInfo.uin 为准，不信任前端伪造）：

submitMlsFeedback 主要入参：

closeMyMlsFeedback 入参： id（必填）、remark（可选，≤512）

状态： pending 待受理 → processing 处理中 → replied 已回复 → closed 已关闭（不可重开）。后台处理见 Admin 菜单「用户反馈」。

表结构：sql/mls_feedback.sql；菜单：sql/mls_feedback_manage_menu.sql。

【2026-09-22 变更摘要】OpenTool getUserMlsTaskList 下发 job_param 移除 sceneCode 字段

• OpenTool getUserMlsTaskList 下发的 job_param 中不再包含 sceneCode 字段；服务端仍会读取该字段用于内部逻辑（如查询翻译提示词），但不再透传给 AI。
• 前端无需改动；AI 侧若依赖 sceneCode，需改用其他方式获取场景信息。

【2026-09-22 变更摘要】新增翻译场景查询接口

• 新增 getMlsTranslationSceneList（§1.3）返回启用的翻译场景列表（mls_translation_scene 表），供前端创建任务时选择场景。
• 创建任务时可在 job_param 中传入 sceneCode 字段（如 "sceneCode": "news"），用于指定翻译场景。
• 服务端在拉取任务时会读取该字段，查询对应的翻译提示词并注入到 job_param.stages.subtitle_translate.prompt 中。

【2026-09-14 变更摘要】P1~P3 项目摘要 / 资源按需接口（新增，不影响旧接口缺省）

新增接口（路径均为 POST /mls/tool/...，需 token；parentUin 与网关一致）：

旧列表接口的 exclude_internal / brief 仍可用，见上一节。前端可灰度切换到新接口，旧调用不受影响。

【2026-09-14 变更摘要】列表/详情可选瘦身（向后兼容）

• 问题：getMlsEpisodeList 等接口按集挂载全量 tasks[]，且每条 task 内嵌同一份含 versions[] 的项目级 jobResource，内部任务（如 TTS 抽卡）堆积时响应可达数十 MB。
• 策略：现有接口加可选参数，缺省行为不变；推荐工作台/项目列表传 exclude_internal=1 + brief=1。
• 入参（getUserMlsList / getMlsDetail / getMlsDramaDetail / getMlsEpisodeList / getMlsEpisodeDetail）：
  • exclude_internal：1 时排除 mls_mode_type.is_internal=1 的任务（迁移见 sql/mls_mode_type_is_internal.sql；未标注时兜底 tts_candidate_generate / tts_candidate_apply）。
  • brief：1 时不回 jobResource / results（及 param / job_param / stages 置空），只保留标识与状态等摘要字段；强制等价于 with_resources=0。
  • with_resources：0 时仅不回 jobResource（仍回 results/param 等）；不传默认回全量资源（兼容旧客户端）。
• P0 建议：列表请求 { "exclude_internal": 1, "brief": 1 }，可将 26MB 级响应降到约 1MB 量级。
• 任务类型：mls_mode_type.is_internal；getMlsModeTypeList 返回 is_internal；管理后台可编辑。

【2026-09-08 变更摘要】候选分组资源独立表

• 表：分组候选资源迁至 mls_resource_file_candidate；mls_resource_file 仅存扁平资源。
• 接口不变：saveMlsCandidateFiles / getMlsResourceGroups / getMlsResourceGroupFiles 入参出参不变，仅存储表切换。
• 软删 / 到期 / ResourceCleanWorker：任务删除时双表软删；物理清理扫描扁平表 + 候选表（按表名+id 回写状态，避免 id 冲突）。
• 迁移：同一文件 sql/mls_resource_file_candidate.sql 分三段复制执行——【Step A】建表 → 发代码 →【Step C】迁数据 → 验证后【Step D】删旧表分组列。

【2026-09-07 变更摘要】分组候选资源改为同键升版本

• §5.6 saveMlsCandidateFiles：不再 upsert 覆盖；与普通资源一样插入新版本并转移 is_latest。
• 分组版本键比扁平更深：(uin, drama_video_id, language, fileType, group_key, group_value, file_name)（无项目时回退 episodeId）。普通资源版本键止于 fileType。
• 同键再次写入：旧 latest 仅 is_latest=0 保留历史；新行 version_seq 递增；uptime 相对旧 latest 严格递增。
• §5.4 分组摘要 fileCount 仍只统计 is_latest=1（避免历史版本撑大数量）。
• §5.5 getMlsResourceGroupFiles：平铺返回该分组下全部版本（含历史），每条含 version / versionSeq / isLatest；data.count 为条数；不嵌套 versions[]。
• 成功响应 data.files[] 仍含 startMs / fileName / uptime（不含 url），并增返 id / version / versionSeq。

【2026-09-04 变更摘要】资源版本键改到项目（集）级

• 术语（文案/文档；JSON 字段名不变）：episodeId = 任务ID；drama_video_id = 项目ID（原「集ID」）；job_id = JOB_ID；mls_drama = 剧（原「剧集」）。
• 扁平资源版本键：由 (uin, episodeId, language, fileType) 改为 (uin, drama_video_id, language, fileType)；episodeId 仅记录来源任务。drama_video_id=0 的孤立任务回退按 episodeId。
• 同项目下不同任务写入相同 language+fileType 一律升新版本并转移 is_latest。
• 迁移回填：sql/mls_resource_file_version_by_drama_video.sql（重排 version_seq，每键仅一条 is_latest=1）。
• OpenTool getMlsJobResource：仍按项目 + is_latest=1 返回（写入修正后 latest 唯一）。
• §5.4 / §5.5：分组资源按项目查；入参仍传任务 episodeId（用于解析所属项目）。
• §5.6 saveMlsCandidateFiles：分组版本键为 (uin, drama_video_id, language, fileType, group_key, group_value, file_name)；【2026-09-07】已改为同键升版本插入，不再 upsert，见文首变更摘要。
• 应用端：videos[].jobResource 与 tasks[].jobResource 均为 最新对象 + versions[]（外层可直接读 id/url；versions 含全部历史，按 version_seq 降序）。数据按项目聚合。getUserMlsList / getMlsDetail 同结构。

【2026-09-03 变更摘要】OpenTool episodeId / job_id 语义对齐

• 字段语义：库内 episodeId = 任务主键（任务ID）；drama_video_id = 项目ID；job_id = JOB_ID（更新/重试会变）。
• getUserMlsTaskList：对外下发的 episodeId = drama_video_id（项目ID）；任务实例用 job_id。
• AI 回调：一律用 job_id（兼容 jobId）定位任务；入参 episodeId 表示项目ID，不参与任务定位；不接收 drama_video_id 入参。
• 不兼容旧 AI：旧链路若只传任务主键 episodeId、或仍把列表里的 episodeId 当任务主键，会找不到任务；须 AI 同步改为按 job_id 回调。
• 涉及接口：updateMlsResult、updateMlsJobStatus、saveMlsResourceFile、saveMlsCandidateFiles、getMlsJobResource。
• 建议加索引：mls_list(job_id)，见 sql/mls_list_job_id_index.sql。

【2026-08-28 变更摘要】job_param 透传 + TTS 候选分组资源

• mls_list.job_param：结构化业务参数 JSON（与 param 环境变量分离），入参/出参字段名统一为 job_param；创建/更新透传、不做业务字段校验。详见 附录 D、§4 / §5 / §18.7。迁移：sql/mls_list_job_param.sql。
• mls_resource_file 新增 group_key / group_value / file_name：普通资源三者为空；候选等分组资源非空。迁移：sql/mls_resource_file_group.sql。
• OpenTool saveMlsCandidateFiles（§5.6）：按 startMs 分组写入；同 (group, fileName) 升版本插入（见【2026-09-07】）；成功返回 data.files[]（startMs/fileName/uptime，不含 url）。
• getMlsJobResource / jobResource：默认不返回分组资源；按需用 §5.4 getMlsResourceGroups、§5.5 getMlsResourceGroupFiles（仅 tool / 应用端）。
• 管理后台任务列表同样只带扁平资源 + groupedResources 摘要；分组明细走懒加载接口。

【2026-08-27 变更摘要】任务调度优先级 + 资源多版本 + 应用端隐藏类型单价

• mls_mode_type.priority：AI 调度优先级（0–999，越大越先被拉取）；创建任务时快照写入 mls_list.priority。迁移：sql/mls_mode_type_priority.sql。管理后台任务类型设置可配置。
• getUserMlsTaskList 已按 priority DESC, episodeId ASC 排序；此前任务默认 priority=0，配置类型后即可生效。
• getMlsModeTypeList（应用端）：不再返回 price_per_second / base_price_per_second / lang_price_per_second；新增 billing_mode: "stage"。计费展示请用 getMlsStageList / checkMlsAmount.required。
• mls_resource_file 多版本：新增 version_seq、version_label、is_latest。迁移：sql/mls_resource_file_version.sql。同键原为 (uin, episodeId, language, fileType)；【2026-09-04】已改为 (uin, drama_video_id, language, fileType)，见文首变更摘要。默认版本号 v{seq}-{YYYYMMDD}。
• jobResource（getUserMlsList / getMlsDetail / 集详情）：每项含 version、versionSeq、isLatest 及 versions[] 历史列表（仅 fileStatus=1）；有项目时按 项目 聚合。
• OpenTool getMlsJobResource：仅返回各键 latest 一条；id / url / source / uptime 与改版前一致，可额外带 version / versionSeq / isLatest，不含 versions 数组。
• saveMlsTaskResource：上传/编辑均 插入新版本（旧版保留，is_latest 转移）；返回 id、version、versionSeq。
• deleteMlsTaskResource：不可删除 latest（方案 A）；仅可删历史版本。
• 新增 copyMlsTaskResourceVersion：从历史版本 sourceId 复制内容升为新 latest（版本号后缀 -copy）。
• 资源清理：仍随任务/集删除批量 is_del=1，由既有 ResourceCleanWorker 物理清理；无单独历史版本 TTL。

免登录接口的完整列表以网关 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-08-18 变更摘要】按 stage 计费（价目表 + executedStages）

• 新增表 mls_stage（阶段单价）与 mls_stage_charge（扣费幂等）。迁移脚本：sql/mls_stage_billing.sql。价目 Redis 缓存键 mls_stage_map，TTL 3600 秒。
• mode_type 不再当计费公式：仍用于列表/Tab、是否需语种/原片、套餐 stages 模板。实扣看回调 executedStages（status=success 才扣，executionId 去重；未知 stageId 跳过、不影响回调结果）。reusedStages / requestedStages、任务最终成败不参与 stage 计费。
• 计费秒：billable_seconds = max(duration, 30)；单次 = billable_seconds × 当时价目单价（回调读当前价目，不在创建时快照）。
• 擦除只认 subtitle_erase / subtitle_erase_fullscreen，不再用 mode_type 打包价。时间戳校对改为跑了 subtitle_calibration 就扣；param.CONSOLE_SUBTITLE_TIMESTAMP_CHECK 仅 legacy 无 stages 任务仍加 1×计费秒。
• 存储：max(duration,30)×storage 单价×本次新增成片条数。成片 = results 里某语种首次 status=2 且 url 非空（审核降为 4 也算已产出）。幂等键 storage:{episodeId}:{lang}。updateMlsJobStatus 仅翻译无 url → 存储 0。
• 源视频：有 origin_url 的集入库成功后扣一次 max(duration,30)×source_upload 单价。无源片占位不扣；预处理重试/任务重试/后补语种不扣。幂等键 source_upload:{dramaVideoId}。挂在 addMlsDramaVideo / addMlsTask 自动建集。
• 预估/预占：有 stages 快照或套餐模板 → Σ once 单价×billable + Σ per_language 单价×billable×语种数；含 compose 再加存储×语种数；预占 = max(0, 预估 − 该 episode 已扣 mls_stage_charge.amount)。仅 resStatus∈{0,1} 且 is_pay=0。无 stages 且套餐模板也空 → 回退旧 base/lang 公式（在途 legacy）。
• 创建/下发：传了非空 stages → 写入快照，拉任务 mode_type=custom + stages，不要求和模板一致。没传则用套餐模板。source_upload / storage 不得下发给 AI。
• 回调切流：请求带 executedStages 键（哪怕空数组）走新逻辑；未带该键 → 旧 calcMlsCallbackChargeParts，避免老 AI 双计/0 扣。
• 新增 getMlsStageList（§1.2）返回阶段单价，供控制台展示。getMlsModeTypeList 的 base_price_per_second / lang_price_per_second 仍返回，仅作 legacy 兼容展示，不要用来算 stages 任务预估；预估以 checkMlsAmount.required 为准。
• 用户侧前端可不改：不传 stages 即可；getMlsAmount / checkMlsAmount / addMlsTask 入参出参字段兼容。源视频扣费默认不计入 checkMlsAmount，需一并校验时传 include_source_upload=1。

【2026-08-12 变更摘要】集 list_type 检索类型

• mls_drama_video 新增 list_type（默认 custom），用于集列表按类型检索；迁移脚本：sql/mls_drama_video_list_type.sql，历史回填：scripts/mls_drama_video_list_type_backfill.sql。
• addMlsDramaVideo、addMlsTask（自动建集时）可选入参 list_type；不传默认 custom。
• getMlsEpisodeList 可选入参 list_type（精确匹配，不传返回全部）。
• 剧集详情 / 集列表 / 集详情返回集字段 list_type。

【2026-08-12 变更摘要】资源文件 drama_video_id

• mls_resource_file 新增 drama_video_id（所属集 ID）；迁移脚本：sql/mls_resource_file_drama_video_id.sql，历史回填：scripts/mls_resource_file_drama_video_id_backfill.sql。
• saveMlsResourceFile（OpenTool）/ saveMlsTaskResource / addMlsTask（resources 入库）写入时带上该字段；入参可传 drama_video_id，不传则按 episodeId 查 mls_list 回填。
• OpenTool getMlsJobResource：资源按集查。drama_video_id 与 episodeId 不能同时为空；有 drama_video_id 直接查，无则用 episodeId 解析出集 ID 再查。job_id 已忽略。

【2026-07-28 变更摘要】注册/登录自动注册支持来源 source

• register、login（短信验证码未注册自动建号）新增可选入参 source，写入 mls_user.source；不传或空串时默认 H5。
• apaas 换票（非 ady）仍固定写 source=apaas；渠道用户写 platform_code。

【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-29 变更摘要】任务类型执行形态（legacy / stages）与 custom 下发

• mls_mode_type 新增 execution_mode（legacy|stages，默认 legacy）与 stages（JSON 阶段模板）。迁移脚本：sql/mls_mode_type_stages.sql。
• mls_list 新增 stages 任务级执行快照（创建/重试写入；空则下发时回退套餐模板）。
• 双层模型：库内 / 用户侧仍存、展示业务 mode_type（计费套餐）；AI 侧对 execution_mode=stages 的任务，OpenTool getUserMlsTaskList 下发 mode_type=custom + stages，并附带 biz_mode_type（业务编码，AI 可忽略）。
• legacy：行为不变，原样下发业务 mode_type，不带 stages。
• stages：管理后台配置非空 stages；创建任务主路径只传业务 mode_type 即可。可选传 stages 自由拼装（stageId+policy），不再要求与模板集合一致；传了非空 stages 则下发 custom。
• 禁止 将字面量 custom 配置为业务套餐编码（custom 仅为 AI 执行态）。
• 计费（已被 2026-08-18 覆盖）：有 stages 时按阶段价目 + executedStages 实扣；无 stages 的在途 legacy 仍用 base/lang。详见文首 【2026-08-18 变更摘要】。
• retryMlsTask：stages 类型会按最新套餐模板刷新任务 stages 快照；可传 stages 自由覆盖。

【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-08-18 更新）：有 stages 时按 mls_stage 单价 × 计费秒（once / 按语种）+ 成片存储 + 源视频上传；无 stages 回退旧公式 max(时长,30)×(base+lang×N+(timestamp_check?1:0))。详见文首 【2026-08-18 变更摘要】。
• 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": []
  }
}

1-a. /mls/tool/getMlsTimbreList - 获取音色列表

管理后台维护的音色库查询接口，供 App 选用音色。默认仅返回 enable=1 的记录。

入参

出参 data

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

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

入参

出参

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

上表仅为示例。stages 类型的真实单价以 mls_stage / getMlsStageList 为准，不要用 base/lang 在前端自行估算。execution_mode=stages 时填写 stages 模板即可，无需 AI 再增加 mode_type。

请求示例

{
  "token": "xxx"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "mode_type": "full_pipeline",
      "mode_name": "全流程",
      "mode_type_index": "full_pipeline",
      "billing_mode": "stage",
      "requires_language": true,
      "requires_origin": true,
      "execution_mode": "legacy",
      "stages": [],
      "remark": "多语言全流程输出：前置+语种叠加"
    },
    {
      "mode_type": "subtitle_erase_dialog",
      "mode_name": "字幕擦除-对话",
      "mode_type_index": "subtitle_erase",
      "billing_mode": "stage",
      "requires_language": false,
      "requires_origin": true,
      "execution_mode": "legacy",
      "stages": [],
      "remark": "不需选语种"
    },
    {
      "mode_type": "demo_stages_pipeline",
      "mode_name": "示例阶段流水线",
      "mode_type_index": "demo_stages",
      "billing_mode": "stage",
      "requires_language": true,
      "requires_origin": true,
      "execution_mode": "stages",
      "stages": [
        {"stageId": "subtitle_translate", "policy": "complete"},
        {"stageId": "tts", "policy": "complete"},
        {"stageId": "compose", "policy": "complete"}
      ],
      "remark": "下发 AI 时转为 mode_type=custom + stages"
    }
  ]
}

1.3 /mls/tool/getMlsTranslationSceneList - 获取翻译场景列表

获取启用的翻译场景列表（读 mls_translation_scene 表，服务端 Redis 缓存约 1 小时）。创建任务前先调此接口，用于渲染场景下拉。

缓存说明：场景列表有 Redis 缓存（TTL 1 小时），管理后台修改场景数据后最多 1 小时生效。如需立即生效，可调用管理后台接口清除缓存。

入参

出参

使用场景

• 前端创建任务时，可调用此接口获取可选的翻译场景列表。
• 用户选择场景后，将 scene_code 作为 job_param.sceneCode 传入创建任务接口。
• 服务端在拉取任务时会读取该字段，查询对应的翻译提示词并注入到 job_param.stages.subtitle_translate.prompt 中。

示例响应

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "id": 1,
      "scene_code": "news",
      "scene_name": "新闻",
      "enable": 1,
      "remark": "新闻类内容翻译"
    },
    {
      "id": 2,
      "scene_code": "entertainment",
      "scene_name": "娱乐",
      "enable": 1,
      "remark": "娱乐类内容翻译"
    }
  ]
}

1.2 /mls/tool/getMlsStageList - 获取阶段计费价目

读 mls_stage（Redis 缓存约 1 小时），供控制台展示单价。不参与鉴权以外的业务写入。虚拟阶段 storage、source_upload 会出现在列表中，但不会下发给 AI。

入参

出参

默认价目（以库配置为准）

单价为 0 的阶段成功执行仍写幂等记录（金额 0）。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "stage_id": "audio_separate",
      "stage_name": "音频分离",
      "price_per_second": 1,
      "bill_scope": "once",
      "sort": 20,
      "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 的成功资源；不含分组资源如 ttsCandidate，分组请用 §5.4 / §5.5）：

• 应用端列表/详情：每项含 versions[] 全量历史（按 versionSeq 降序）；顶层字段与当前 latest 一致。
• OpenTool getMlsJobResource：不含 versions；每项 id / url / source / uptime 不变，可增 version / versionSeq / isLatest。

{
  "original": {
    "subtitle": {
      "id": 14,
      "url": "https://xxx/chat.srt",
      "version": "v2-20260827",
      "versionSeq": 2,
      "isLatest": true,
      "source": "upload",
      "uptime": 1798732799,
      "versions": [
        { "id": 14, "url": "https://xxx/chat.srt", "version": "v2-20260827", "versionSeq": 2, "isLatest": true, "source": "upload", "uptime": 1798732799 },
        { "id": 12, "url": "https://xxx/old.srt", "version": "v1-20260820", "versionSeq": 1, "isLatest": false, "source": "upload", "uptime": 1798640000 }
      ]
    }
  }
}

• 外层 key 为语种（原文字幕等为 original）。
• 内层 key 为资源类型 fileType（如 subtitle、voice、audioRaw、asrSubtitle、cloneVoice 等）。
• 应用端每项含原有四字段 + 版本扩展字段，并含 versions 数组。
• OpenTool getMlsJobResource 每项含原有四字段 + 可选版本扩展字段，无 versions。

请求示例

{
  "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": {},
      "job_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-08-28 变更】data 额外包含 job_param（JSON 对象，非字符串），无配置时为 {}。规则见 附录 D。

【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": {},
    "job_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-08-28 变更】新增可选入参 job_param（object）：结构化业务参数，原样入库透传，不做业务字段校验；不传或 {} 表示无。规则见 附录 D。

【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 顺序取第一个可解析时长的资源写入任务时长并走既有计费预占。

【2026-08-18 变更】可选入参 stages：传了非空数组则自由拼装写入快照并下发 custom（不要求和套餐模板一致）；不传则用套餐模板。legacy 类型也可传 stages。计费见文首 【2026-08-18 变更摘要】。有源片自动建集时会先扣 源视频上传（与任务预占分开）。

【2026-08-12 变更】新增可选入参 list_type：自动创建集时写入集表；不传默认 custom。传已有 drama_video_id 时不改集的 list_type。

入参

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 / job_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"
  },
  "job_param": {
    "subtitleIDs": {"12": "12"},
    "candidateCount": 4
  }
}

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

{
  "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（处理中）时不允许修改。

【2026-08-28 变更】新增可选入参 job_param（object）：不传则不改，传 {} 清空。规则见 附录 D。

入参

出参

请求示例

{
  "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）。

• 新增/编辑：均 插入新版本；同键旧 latest 仅降 is_latest，历史版本保留。
• resStatus=1（处理中）不允许操作。
• 入库时自动写入 drama_video_id（从任务 mls_list 读取）。

入参

出参

请求示例（新增）

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

请求示例（编辑/覆盖）

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

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

软删指定历史素材（is_del=1）。当前 latest 不可删除；请用上传或 copyMlsTaskResourceVersion 覆盖。resStatus=1 处理中不允许删除。

入参

出参

请求示例

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

5.3 /mls/tool/copyMlsTaskResourceVersion - 从历史版本创建副本

基于选中历史版本的内容（fileUrl 等）生成新版本并设为 latest；版本号形如 v3-20260827-copy。

入参

出参

请求示例

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

5.4 /mls/tool/getMlsResourceGroups - 分组资源：分组列表

按语种 + fileType 查询分组摘要（不含文件明细）。用于 TTS 候选等「一类型多文件、按 ID 分组」的资源；jobResource / OpenTool getMlsJobResource 默认不返回这类数据。

【2026-09-04】按 项目（drama_video_id） 聚合查询。可传 drama_video_id（项目ID） 直接按集查；或传 episodeId（任务ID） 由服务端解析所属项目。二者至少传一；都传时以 drama_video_id 为准。无项目的孤立任务回退按任务查。

【2026-09-07】fileCount / 列表仅统计 is_latest=1 的分组文件（历史版本不计入）。

应用端路径：POST /mls/tool/getMlsResourceGroups（需 token）。不再提供 OpenTool 路径。

入参

出参

请求示例

{
  "token": "xxx",
  "episodeId": 1,
  "language": "english",
  "fileType": "ttsCandidate"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      { "groupKey": "subtitleID", "groupValue": "12", "fileCount": 2, "uptime": 1798732800 },
      { "groupKey": "subtitleID", "groupValue": "18", "fileCount": 4, "uptime": 1798732810 }
    ]
  }
}

5.5 /mls/tool/getMlsResourceGroupFiles - 分组资源：某分组文件列表

查询指定分组下的文件明细。

【2026-09-04】与 §5.4 相同：按项目聚合；可传 drama_video_id 或 episodeId（至少其一）。

【2026-09-07】平铺返回该分组下全部版本（含历史，按 fileName ASC、versionSeq DESC）；每条含 version / versionSeq / isLatest；data.count 为总条数；不嵌套 versions[]。

应用端路径：POST /mls/tool/getMlsResourceGroupFiles（需 token）。不再提供 OpenTool 路径。

入参

出参

请求示例

{
  "token": "xxx",
  "episodeId": 1,
  "language": "english",
  "fileType": "ttsCandidate",
  "groupKey": "subtitleID",
  "groupValue": "12"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "groupKey": "startMs",
    "groupValue": "0",
    "count": 6,
    "list": [
      {
        "id": 12585,
        "fileName": "final_omnivoice_1.wav",
        "url": "https://cdn.example/v2.wav",
        "source": "backend",
        "uptime": 1788771486,
        "version": "v2-20260907",
        "versionSeq": 2,
        "isLatest": true,
        "episodeId": 1703,
        "drama_video_id": 1760
      },
      {
        "id": 12582,
        "fileName": "final_omnivoice_1.wav",
        "url": "https://cdn.example/v1.wav",
        "source": "backend",
        "uptime": 1788771486,
        "version": "v1-20260907",
        "versionSeq": 1,
        "isLatest": false,
        "episodeId": 1702,
        "drama_video_id": 1760
      }
    ]
  }
}

5.6 OpenTool /openApi/mls/saveMlsCandidateFiles - 批量保存分组候选文件

处理节点按字幕目录上传候选音频后调用。写入 mls_resource_file_candidate（分组行：group_key / group_value / file_name）。与扁平表 mls_resource_file 分离。

【2026-09-07】同键升版本插入，不再覆盖：版本键 (uin, drama_video_id, language, fileType, group_key, group_value, file_name)（无项目时回退 episodeId）；仍写入来源任务 episodeId。行为对齐普通资源（普通资源版本键止于 fileType），分组资源再深到 group_key / group_value / file_name。同键再次保存时：旧 latest 仅降 is_latest，插入新行并递增 version_seq；uptime 相对旧 latest 严格递增。

同一次请求的 files 必须属于同一 startMs，可含多个 fileName；同请求内 fileName 不可重复。

入参

files[] 单项：

请求示例

{
  "episodeId": 1,
  "uin": 12345,
  "parentId": "01",
  "language": "english",
  "jobId": "candidate-001",
  "fileType": "ttsCandidate",
  "files": [
    { "startMs": 20533, "fileName": "candidate-a.mp3", "url": "https://cdn.example/a.mp3" },
    { "startMs": 20533, "fileName": "candidate-b.wav", "url": "https://cdn.example/b.wav" }
  ]
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "files": [
      {
        "startMs": 20533,
        "fileName": "candidate-a.mp3",
        "uptime": 1788427288,
        "id": 101,
        "version": "v2-20260907",
        "versionSeq": 2
      },
      {
        "startMs": 20533,
        "fileName": "candidate-b.wav",
        "uptime": 1788427289,
        "id": 102,
        "version": "v1-20260907",
        "versionSeq": 1
      }
    ]
  }
}

data.files[] 每项返回本次请求对应资源的 startMs / fileName / uptime，不返回 url；并返回新版本 id / version / versionSeq。uptime 为正整数秒级时间戳，同一版本键再次写入时严格递增。处理节点按 (startMs, fileName) 匹配响应并写入候选索引。

上线前需执行 sql/mls_resource_file_group.sql。

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 中返回。

【2026-08-18 变更】传了 stages 则写入快照；execution_mode=stages 且未传则刷新套餐模板。重试不重复扣源视频。

任务已完成（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。

【2026-07-28 变更】resStatus=1（处理中）的任务禁止删除，返回 flag=110「任务处理中，禁止删除」。

入参

出参

请求示例

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

返回示例

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

处理中禁止删除：

{
  "flag": 110,
  "flagString": "任务处理中，禁止删除"
}

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 且 is_pay=0）的预占额度。

【2026-08-18 变更】预占与 checkMlsAmount 共用 sumMlsUinReservedCost：任务有 stages 快照或套餐模板时为「阶段预估 − 该 episode 已扣 mls_stage_charge」；否则回退旧 base/lang（含未成功语种）。前端入参/出参字段不变。

【2026-06-11 变更】预占按每条待处理任务计算（公式已被 2026-08-18 覆盖）。

入参

出参

【变更】 当前版本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": "《示例短剧》120秒扣240：英语翻译120，英语成片存储120",
      "episodeId": 5,
      "uptime": 1704067200,
      "task_title": "示例短剧"
    }
  ],
  "total": 1
}

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

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

【2026-08-18 变更】有 stages（入参或套餐模板）时 required 按阶段价目预估（含 compose 则加存储×语种数）；无 stages 回退旧 base/lang + 时间戳校对。reserved 同 getMlsAmount。可选 stages、include_source_upload。

【2026-06-11 变更】计费规则按 mode_type 区分（配置见 getMlsModeTypeList）；stages 任务请以本接口 required 为准，不要用返回的 base_price_per_second/lang_price_per_second 自行相乘。

legacy 公式（无 stages）：required = max(duration, 30) × (base_price_per_second + lang_price_per_second × N + (timestamp_check ? 1 : 0))

stages 公式：once 单价×billable + per_language 单价×billable×语种数；含 compose 再加 storage 单价×billable×语种数。计费秒 billable = max(duration, 30)。

不足 30 秒按 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 锁任务行 + 锁额度行）。

• 新路径（回调带 executedStages 键，哪怕空数组）：按成功阶段扣费 + 首次成片存储；bill_base_paid / bill_addon_ts_paid 保持原值。未知 stage 跳过。
• 旧路径（未带该键）：全流程 updateMlsResult / 需语种非全流程 updateMlsJobStatus：首次成功扣前置（及时间戳校对加价），每个新成功语种扣叠加费；不需语种任务成功时扣前置（及时间戳）。已扣标记不重扣。
• 后付费无退费。若用户开启成片审核，成功结果可能以 status=4 入库；存储按「首次成功且 url 非空」计，与是否降为 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-07-28】 当前实现支持 3 种登录方式：

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

其中“手机号 + 短信验证码”模式下，若手机号未注册会自动创建账号后登录；可传可选入参 source 写入注册来源。

登录成功后返回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",
  "source": "H5"
}

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-07-28】 手机号注册，需短信验证码校验通过。支持传入注册来源 source。

入参

说明

• 注册时会先调用外部账户服务创建底层账号并获取uin
• mls_user.password入库使用PASSWORD('{$password}')
• source 写入 mls_user.source（如 H5 / apaas / 渠道 code 等）

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或其子域，或属于环境变量MLS_ALLOWED_REDIRECT_DOMAINS（逗号分隔根域白名单，同样允许子域名）。多前端域名（如weapp.yaomuai.com、mls.yaomuai.com）请配置例如MLS_ALLOWED_REDIRECT_DOMAINS=yaomuai.com。

返回示例

{
  "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 不是同一类）。

入参

域名校验：与getWechatMpAuthUrl相同——DOMAIN或其子域，或MLS_ALLOWED_REDIRECT_DOMAINS白名单根域（含子域）。

返回示例

{
  "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 失败。

executedStages 单项：

非全流程回调见 OpenTool updateMlsJobStatus（字段同样支持 executedStages）。

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

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

• 对本次回调中「新成功」的语种（该语种合并前在库中状态不是 2）：入库时status记为 4（待审核），而不是 2。
• 积分：带 executedStages 时按阶段 + 成片存储扣；未带该键时仍按管道上报成功(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）。
• 支付宝：默认电脑网站支付（alipay.trade.page.pay，返回form_html）；显式alipayScene=scan时用当面付 precreate（EasySDK）。异步通知验签用 EasySDK。默认走正式网关openapi.alipay.com；仅当MLS_ALIPAY_SANDBOX=1时才用沙箱。

微信支付

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

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

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

支付宝

优先支持开放平台 公钥证书模式（与其它业务共用同一应用时推荐）；未配证书时回退密钥模式。

证书模式最小配置示例（三件套已放在library/common/pay/alipayCert时）：

MLS_ALIPAY_APP_ID=2021001159681017
MLS_ALIPAY_PRIVATE_KEY=/path/to/应用私钥RSA2048.txt
# 证书目录可不配，默认读 library/common/pay/alipayCert

成功走证书模式时，下单返回里signMode为cert；form_html中会带app_cert_sn、alipay_root_cert_sn。

支付宝报invalid-signature时：

1. 确认开放平台是「公钥证书」且代码已配证书三件套 + 同一把应用私钥。
2. 应用私钥必须与appCertPublicKey_*.crt成对（用开发助手生成的那把，不要用错环境/错应用的私钥）。
3. 证书模式下不要再依赖MLS_ALIPAY_PUBLIC_KEY冒充验签。
4. 商品名称（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（默认 page）：form_html→ 见下文「支付宝电脑网站支付：前端对接」；另回显returnUrl、alipayScene、signMode（cert/key）
• 支付宝扫码：传alipayScene=scan时返回qr_code（需当面付/订单码产品）

支付宝电脑网站支付：前端对接（推荐）

当前 PC 充值页应对齐「电脑网站支付」：用户选支付宝后跳转支付宝收银台（不是页内二维码；页内码需当面付/订单码）。

推荐流程

1. 拉商品：POST /mls/tool/getMlsGoodsList（需登录）
2. 用户选商品 + 选支付宝
3. 调POST /mls/tool/createMlsOrderAndPay：

{
  "Tag": "createMlsOrderAndPay",
  "token": "<登录token>",
  "goodsId": 6,
  "payType": 2,
  "amount": 1,
  "returnUrl": "https://你的前端域名/#/recharge?from=alipay"
}

说明：payType=2；alipayScene可省略（默认page）；自定义商品才传amount；returnUrl建议传充值页（须落在DOMAIN/MLS_ALLOWED_REDIRECT_DOMAINS）。

4. flag===100 时取data.form_html，在浏览器中提交跳转：

// axios/fetch 已 JSON 解析后的对象，直接用字符串，不要二次 stringify
function goAlipayPagePay(formHtml) {
  if (!formHtml) throw new Error('缺少 form_html');
  // 方式 A：当前页跳转（简单）
  const div = document.createElement('div');
  div.style.display = 'none';
  div.innerHTML = formHtml;
  document.body.appendChild(div);
  const form = div.querySelector('#alipaysubmit') || div.querySelector('form');
  if (!form) throw new Error('form_html 无效');
  form.submit();

  // 方式 B：新窗口（注意弹窗拦截，需在用户点击事件里同步打开）
  // const w = window.open('', '_blank');
  // w.document.write(formHtml);
  // w.document.close();
}

5. 支付结果展示（重要）：
   • 入账只认异步回调/mls/tool/alipayPayNotify，不要用returnUrl同步回跳参数当作已支付。
   • 用户从支付宝回到returnUrl后：订阅 DMS messages/mls_pay_success_{uin}，或轮询getMlsAmount刷新余额；可提示「支付处理中」。
   • 成功后关闭支付中态、刷新积分展示。

UI 建议（相对微信扫码）

不要对支付宝默认走画qr_code（除非已开通当面付/订单码且传alipayScene=scan）。

联调注意

• 接口返回的form_html是 HTML 字符串；从网络面板复制时若带\"，须先JSON.parse还原（可用项目内mls/alipaytest.html粘贴整段 JSON 自动还原）。
• 成功配置证书时data.signMode应为cert；form_html内应含app_cert_sn。
• 改密钥/证书后须重新下单拿新form_html，旧表单会验签失败。

15. /mls/tool/createMlsOrder - 下单

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

入参

出参

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

根据下单结果调起支付：PC 端微信返回code_url；支付宝默认返回form_html（电脑网站支付）；传alipayScene=scan时返回qr_code。

入参

出参

按支付方式返回：

• 微信 NATIVE（PC）：data.code_url→ 生成二维码，用户微信扫码
• 微信 JSAPI（微信内）：data含appId、timeStamp、nonceStr、package、signType、paySign，用于前端调起微信支付
• 支付宝网页（默认）：data.form_html→ 新窗口写入并提交
• 支付宝扫码：传alipayScene=scan时返回data.qr_code

支付完成回调（免登录）

由微信/支付宝服务器 POST 调用，无需 token。网关已将wechatPayNotify、alipayPayNotify列入免登录。

• 微信异步通知：POST /mls/tool/wechatPayNotify
• 支付宝异步通知：POST /mls/tool/alipayPayNotify（下单时写入的notify_url）

支付宝回调处理要点（服务端已实现）

1. EasySDKverifyNotify验签（证书模式从支付宝公钥证书取公钥）
2. 仅TRADE_SUCCESS / TRADE_FINISHED入账；其它状态回success避免无效重试
3. 校验total_amount与本地mls_pay_data.amount（分）一致
4. 已支付订单幂等回success；验签/金额失败回fail（支付宝会重试）
5. handlePaySuccess：status=0→1乐观锁防并发重复加积分，写流水（trade_type=1存入）、DMS、财务收款

验签通过且支付成功时系统会：

1. 更新mls_pay_data（status=1、orderId=支付宝trade_no、payTime）
2. 增加mls_user_amount并写入mls_user_amount_run（trade_type=1，说明「积分充值」）
3. DMS 推送messages/mls_pay_success_{uin}
4. 同步mls_finance_receipt（source=alipay）

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

DMS 推送内容

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